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random(3) 

C8h(l) 

addbib(l) 

roffbib(l) 

8ortbib(l) 

indxbib(l) 

indxbib(l) 

biff(l) 

comsat  (8C) 

wherci5(l) 

8trings(l) 

uuencode(lC) 

fread(3S) 

bind(2) 

bind(2j 

binmail(l) 

bstring(3) 

bdemos(6) 

strip(l) 

bk(4) 
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bw  -  Sna 
sjQc  -  apd&te  the  super 
eync  -  update  super- 
sync  -  updftte  the  super 
update  -  periodically  update  the  super 
sisbiock  - 
sigpause  *  atomically  release 
sum  -  sum  and  count 
-  stand  alone  test  for  the  Sun  video  (^aphics 
boggle  -  play  the  game  of 

ching  -  the 
reboot  -  UNIX 
mille  -  play  Mi  lie 
indxbib  -  make  inverted  index  to  a  bibliography 
sir  itch:  multi-way  command 
login,  new  grp,/  sh,  for,  case,  if,  while, 


fr 


more,  page  - 

bw  *  Sun  black  and  white  frame 
fread,  fwrite  - 
stdio  -  standard 
setbuf,  setbuffer,  setlinebof  -  assign 
fbio  -  general  pro  pert  iee  of  frame 
generate  a  dump  of  the  operating  system^s  profile 

mknod  - 
conftg  - 

-  print  out  manual  pages;  find  manual  information 
mkstr  -  create  an  error  message  file 
ttytype  -  data  base  of  terminal  types 
ntohs  -  convert  values  between  host  and  network 
bcopy,  bcmp,  bsero,  ffs  -  bit  and 
swab  -  swap 
bcopy,  bcmp, 
cc  - 
cpp  -  the 
cb  - 

indent  -  indent  and  format 
lint  -  a 

xstr  -  extract  strings  from 
mkstr  -  create  an  error  message  file  by  musaging 

bypot, 

dc  *  desk 
cal  *  display 


syscall  -  indirect  system 
gprof  -  display 
getnid,  getgid  -  get  nser  or  group  ID  of  the 
matloc,  free,  reatloc, 
intro  -  introduction  to  system 
Canfield,  cfscorei  -  the  solitaire  card  game 

Canfield, 
printcap  -  printer 
termcap  -  terminal 
oct  ~  Central  Data  octal  serial 
Canfield,  cfscoret  -  the  solitaire 
cribbage  -  the 

exec,  exit,  export,  login,  newgrp,  read,/  sh,  for, 


cai&man  -  create  the 
ccat  ~  compress  and  uncompress  files,  and 

default: 


them,  compact,  uncompaci. 


sh,  for,  case,  if,  while,  break,  continue. 


black  and  white  frame  buffer.  . 

block . 

block . . . . . 

block.  . . .  •  ♦ 

block . 

block  signals . 

blocked  signals  and  wait  for  interrupt . 

blocks  in  a  file . 

board,  gxtest  . 

boggle . 

boggle  -  play  the  game  of  boggle.  . . 

book  of  changes  and  other  cookies . 

bootstrapping  procedures . .  •  «  « 

Bomes . * . 

.br  lookbib  -  find  references  in  a  bibliography.  . 

branch . . . . . 

break,  continue,  cd,  eval,  exec,  exit,  export . 

break:  exit  while/foreach  loop.  . . 

breakrw:  exit  from  switch.  . . 

bring  job  into  foreground . . . 

brk,  sbrk  -  change  data  segment  siie. . 

browse  through  a  text  file . 

bsnncube  *  view  3-D  Sun  logo. . 

buffer.  . 

buffered  binaiy  input/output . 

buffered  input/output  package . 

buffering  to  a  stream.  .  «  . . *  «  • 

buffers . . 

buffers,  kgmon  -  «  •  •  . . 

build  special  file . 

build  system  configuration  files.  * . .  •  » 

bw  -  Sun  black  and  white  frame  buffer . 

by  keywords,  man  . 

by  massaging  C  source.  *  •  . . .  «  • 

by  port.  . . 

byte  order,  htonl,  htons,  ntohl,  . . .  • 

byte  siring  operations . . 

bytes . . . 

bsero,  ffs  -  bit  and  byte  string  operations . 

C  compiler . 

C  language  preprocessor.  . 

C  program  beautifier.  «  «  *  .  . . 

C  program  source . 

0  program  verifier.  . . . 

C  programs  to  implement  shared  strings . .  ,  • 

C  source . 

cabs  -  Euclidean  distance . .  .  .  • 

cal  -  display  calendar . .  •  *  • 

calculator . 

calendar.  . . 

calendar  -  reminder  service.  «  ,  .  .  . . *  ,  . 

call . 

call  graph  profile  data . 

caller . 

calloc,  cfree,  altoca  -  memory  allocator . 

calls  and  error  nnmbeis.  .  .  »  * . 

Canfield . . . . 

Canfield,  cfscores  -  the  solitaire  card  game . 

capability  data  base . . . 

capability  data  base . . 

card . 

card  game  canfield . . 

card  game  cribbage . 

case,  if,  while,  break,  continue,  cd,  eval . 

case:  selector  in  switch.  ..  . . 

cat  concatenate  and  display . 

cat  files  for  the  manual . . 

cat  them,  compact,  uncompact,  . 

catchall  danse  in  switch.  . . 

caiman  -  create  the  cat  files  for  the  manual . 

cb  -  C  program  beautifier . . 

cc  -  C  compiler  . 

ccat  -  compress  aud  uncompress  files,  and  cat  . 

cd  -  change  working  directory . 

cd:  change  directory.  . . . 

cd,  eval,  exec,  exit,  export,  login,  newgrp,  read,/  ,  .  .  . 


sync(2) 
sync(8) 
iipdate(8) 
sigb!ock(2) 
sigpanse{2) 
sum(l) 
gxtest  (8s) 
hogglc(6) 
boggIe(6) 
ching(6) 
reboot(8} 
mille(6) 
tndxbib(l) 
csh(l) 

•h(n 
€8h(l 
cshll 
csh(l 
brk(2) 
moi^l) 
bsuncube(6) 
bw(4S) 
fread(3S) 
intro(3S) 
setbaf(SS) 
fb!o(4Sl 
kgmon(8) 
mknod(8) 
config(8) 
bw(4S) 
man(l) 
mkstifl) 
ttytypc(6) 
b^eoniei\3N) 
b8tring(3) 
swab(3) 
batring(3) 

, . 

indent(l) 

lint(l) 

xstxtl) 

mkstifl) 

hypotfSM) 

cal(l) 

dc(l) 

cal(l) 

calendai(l) 

sy8cat](2) 

gprof(l) 

getuid(3F) 

malloc{3) 

intro(2) 

canfieldffi) 

canfietd(6) 

printcap(5) 

tenncap(5) 

oct(4S) 

canfield(6) 

€ribbage(6) 

•1(1) 

C8h(l) 

cat(l) 

catinan{8) 

compact(l) 

C8h(l) 

catman(8) 

cb(l) 

cc(l) 

compact(i) 

cd(l) 

csh(l) 
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dehk. 
fabs,  floor, 

fabs,  floor,  ceil  -  absolute  value,  floor, 

oct  - 

-  Syetech  VPC-2200  Versatec  priuter/plotter  and 
malice,  free,  realloc,  catloc, 
caufletd, 


cbdir  - 
brk,  sbrk  - 
cbdir  - 
chsb  - 
cd: 
cbdir 
iotuii  - 
chgrp  - 
passwd  - 
cbmod  - 
cbmod  • 
cbmod,  fchmod  - 
umask: 
chown  - 
cbown,  febowa  - 
ebroot  - 
signal  - 
ede  - 
rename  - 
delta  -  make  a  delta  ( 
set: 


cd  - 

cbing  -  tbe  book  of 
-  better  random  number  generator;  routines  for 
vi  -  view  a  file  without 
pipe  -  create  an  interprocess  communication 
ungetc  -  push 

/isucit,  isgrapb,  toupper,  tolower,  toascii  *- 
eqncbar  -  special 
getc,  fgetc  -  get  a 
index,  lindex,  Inbtnk,  ten  -  tell  about 
getc,  getchar,  fgetc,  getw  -  get 
putc,  putchar,  fputc,  putw  -  put 
ascii  -  map  of  ASCII 
putc,  fputc  -  write  a 
tset  -  establish  terminal 
tr  -  translate 


snake,  snscore  -  display 


dcheck  -  file  system  directory  consistency 
icheck  -  file  system  storage  consistency 
fptype  - 

fsck  -  file  system  consistency 
cbecknews  - 
cbecknr  - 
eqn,  neqn, 

fastbalt  -  reboot/balt  tbe  system  without 
news  network. 

newtre  -  information  file  for  readnews(l)  and 


closepl  -  graphics/  openpl,  erase,  label,  line, 
isgrapb,  toupper,  tolower,  toascii  -  character 
default:  catchall 
uuclean  -  uuep  spool  directory 


ciri  - 


ede  -  change  the  delta  commentary  of  an  SCCS  .  •  .  *  cdc(l) 

ceil  ^  absolute  value,  floor,  ceiling  functions . floor(3M) 

ceiling  functions . floor(3M) 

Central  Data  octal  serial  card . oct(4S) 

Centronics  printer  interface,  vpc . vpc(4S) 

efree,  alloca  -  memory  allocator  . malloc(3) 

cfscores  -  the  solitaire  card  game  canfield . canfield(6) 

eg  -  Sun  color  graphics  interface. . cg(4S) 

change  current  working  directory.  . chdir(2) 

change  data  segment  size . brk(2) 

change  default  directory.  «  •  . . chdir(3P) 

change  default  login  shell . chsh(l) 

change  directory . cshfl) 

change  directory  . C8h(l) 

change  f77  I/O  initialization . ioinit(3F) 

change  group . chgrp(l) 

change  login  password . pa9swd(l) 

change  mode.  . . . . .  €hmod(l) 

change  mode  of  a  file. . chmod(3F) 

change  mode  of  file . chmod(2) 

change  or  display  file  creation  mask . csh(l) 

change  owner  . chown(8) 

change  owner  and  group  of  a  file . chown(2) 

change  root  directory. . €hroot(2) 

change  the  action  for  a  signal.  «  . . 8igna!(3P) 

change  the  delta  commentary  of  an  SCCS  delta . cdc(l) 

change  the  name  of  a  file . rename(2) 

change)  to  an  SCCS  file . .  «  delta(l) 

change  value  of  shell  variable . C8h(l} 

change  working  directory . cd(l) 

changes  and  other  cookies.  . ching(6) 

changing  generaton.  /srandom,  initstate,  setstate  «  .  ,  ra!idom(3) 

changing  it  using  the  vi  visual  editor . view(l) 

channel . . . pipe{2) 

character  back  into  input  stream . .  ,  .  ung^c(3S) 

character  classification  and  conversion  macros . ctype(3) 

character  definitions  for  eqn . eqnchar(7) 

character  from  a  logical  unit . getc(3F) 

character  objects . . . index(3F) 

character  or  integer  from  stream . .  .  getc(3S) 

character  or  word  on  a  stream . . . putc(3S) 

character  set . a8cii(7) 

character  to  a  FORTRAN  logical  unit . putc(3F) 

characteristics  for  the  environment . . . tset(l) 

characters . tr(l) 

chase  -  Try  to  escape  to  killer  robots . chasc(8) 

chase  game . . . Bnakc(6) 

cbdir  -  change  current  working  directory . chdir(2) 

cbdir  -  change  default  directory.  . . .  chdir(3F) 

cbdir:  change  directoiy.  . . C8h(l) 

check . dcheck(8) 

check . . . icheck(8) 

check  a  floating  point  number . .  .  fptype(3F) 

check  and  interactive  repair. . fsck(8) 

check  if  user  has  news  on  the  USENET  news  network,  .  chcckncw8{l) 

check  nrolf/troff  files . chcckn^l) 

checkeq  *  typeset  mathematics . cqn(l) 

checking  the  disks,  fastboot,  . fastboot(8) 

cbecknews  -  check  if  user  has  news  on  the  USENET  .  .  checknew8(l) 

checknews(l)<  . new8rc(5) 

checknr  -  check  nroff/troff  files . checknif  1) 

chgrp  -  change  group.  . . chgrp(l) 

ching  -  the  book  of  changes  and  other  cookies . ching(6) 

cbmod  -  change  mode . .  chmod(l) 

chmod  -  change  mode  of  a  file . chmod(3F) 

chmod,  fchmod  •  change  mode  of  file . chmod(2) 

cbown  -  change  owner . chown(8) 

chown,  fchown  *-  change  owner  and  group  of  a  file,  .  .  ,  chown(2) 

chroot  -  change  root  directoiy. . chroot(2) 

ebsh  -  change  default  login  shell . ch8h(l) 

circle,  arc,  move,  cont,  point,  linemod,  space,  . plot(3X) 

classification  and  conversion  macros,  /isascii . ctype(3) 

clause  in  switch .  . C5h(l) 

clean-up . uucIcan(8C) 

clear  clear  workstation  or  terminal  screen . clear(i} 

clear  i-node . clri(8) 
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ciciir  - 
ferror,  feof, 

csh  -  &  shell  (comnund  interpreter)  irith 

cron  - 

shutdown  - 
fclose,  fflush  - 

opendir,  renddir,  telldir,  seekdir,  nwiuddlr, 
9yslof»  openlog, 
circle,  Arc.  move,  cont,  point,  linemod,  spnce. 


pi  -  PmcaI  interpreter 


log.  dmesg- 
colordemot  -  demonstnte  Sun 
eg  -  Sun 
Display. 

pr  -  print  (ile(8),  possibly  in  multiple 
colrm  -  remove 

comb  - 
hlei. 

exec:  overlay  shell  with  specified 
time:  time 

-  routines  for  returning  a  stream  to  a  remote 
rexec  return  stream  to  a  remote 
system  -  issue  a  shell 
system  -  execute  a  UNIX 
test  -  condition 
time  -  time  a 
nice,  nohup  -  run  a 
switch:  multi-way 
uux  -  Unix  to  Unix 
rehash:  recompute 
unhash:  discard 
hashstat:  print 
nohup:  run 
esh  -  a  shell  ( 
whatis  -  describe  what  a 
readonly,  set,  shift,  times,  trap,  umask,  wait  - 
getarg.  large  -  return 
repeat:  execute 
rc  - 

ouintr:  process  interrupts  in 
goto: 

else:  alternative 
intro  -  introduction  to 
-  Introduction  to  system  maintenance  and  operation 

at  -  execute 
while:  repeat 
lastcomm  -  show  last 
source:  read 
ede  ~  change  the  delta 
comm  -  select  or  reject  lines 
bk  -  line  discipline  for  machine-machine 
socket  ~  create  an  endpoint  for 
pipe  -  create  an  interprocess 
users  - 
files,  and  cat  them, 
diff  -  differential  file  and  directory 
emp  - 
scesdiff 

diff3  -  $-way  differential  file 
intro  -  introduction  to 
cc  '  C 

S77  -  FORTRAN-77 
pc  -  Pascal 
yacc  -  yet  another  compiler- 
error  -  analyse  and  disperse 
yacc  '  yet  another 
wait:  wait  for  backgronnd  processes  to 
wait  '  await 
compact,  uncoznpact,  ccat  - 


clear  workstation  or  terminal  screen . 

clearerr.  fileno  -  stream  status  inquiries . 

C-like  syntax . . . 

clock  daemon.  . .  »  «  • 

close  -  delete  a  descriptor. . . 

close  down  the  system  at  a  given  time.  . . 

close  or  flush  a  stream . 

closedir- directory  operations.  . . . . 

closelog  -  control  system  fog . . . 

closepi  -  graphics  interface,  /erase,  label,  line . 

ciri  clear  t-node.  . . . . 

emp  •  compare  two  files.  .  . . 

code  translator . * . 

col  -  fitter  revene  paper  motions . 

colcrt  -  filter  nroff  output  for  CRT  previewing.  «  •  *  . 
collect  system  diagnostic  messages  to  form  error  «  .  .  « 

Color  Graphics  Display.  . . . . .  • 

color  graphics  interface . . . .  .  «  • 

cotordemos  -  demonstrate  Sun  Color  Graphics . 

cotnn  -  remove  columns  from  a  file . 

columns . . . 

columns  from  a  file . .  . . 

comb  *  combine  SCC3  deltas.  . . * 

combine  SOCS  deltas.  «  . . . 

comm  -  select  or  reject  tines  common  to  two  sorted  »  •  « 

command . 

command . . . 

command,  remd,  rresvport,  mserok  .  . . 

command . 

command . . . . . 

command . 

command . 

command.  «  *  .  . . 

command  at  low  priority  (sh  only) . 

command  branch . 

command  execution.  . . . 

command  hash  table . 

command  hash  table . 


cleai(l) 

ferroi(3S) 

csh(l) 

cron(8) 

close(2) 

shutdown(8) 

fclo8e(3S) 

directory\3) 

sy8log(3) 

pfot(3X) 

clri(8) 

cmp(l) 

col(l} 

colcrt(l) 

dmes^S) 

colordemos(6) 

erfdS) 

€olordemo8(6) 

colfTn(l) 

P*<1) 

cotrm(l) 

combfl) 

comb(l) 

comm(l) 

csh(l) 

C6h(l) 

rcmd(3N) 

rexcc(3N) 

sy8tcm(3) 

iystem(3F) 

teBt(l) 

time(l) 

nice(l) 

C8h(l) 

uux(lC) 

C8h{l) 

csh(l) 


command  hashing  statistics . .  * 

command  immune  to  hangnps.  .  *  . . 

command  interpreter)  with  C-like  syntax.  »  .  . 

command  is . 

command  language,  /export,  login,  newgrp,  read, 

command  line  arguments . 

command  repeatedly.  . .  .  «  « 

command  script  for  auto-reboot  and  daemons. 

command  scripts.  .  . . * . 

command  transfer.  . 

commands . . . 

commands.  . . 

commands,  intro  . 

commands  at  a  later  time.  . . 

commands  conditionally . *  . 

commands  executed  in  revene  order.  . 

commands  from  file . 

commentary  of  an  SCCS  delta.  . . 

common  to  two  sorted  files . *  *  ♦  • 

communication.  .  .  «  . . 

communication . 

communication  channel.  . . .  , 

compact  (1st  of  users  who  are  on  the  system.  .  . 


.  »  .  C8h(l) 

.  .  •  cshfl) 

«  »  «  C8h(lj 

.  «  *  whatis(l) 

.  •  .  sh(l) 

.  .  •  getarg(3F) 

«  •  •  csh(l) 

,  .  .  rc(8) 

.  •  •  cshfl) 

»  •  .  cshfl) 

.  •  ♦  csh(l) 

•  .  .  introfl) 

.  «  •  introfS) 

.  .  .  at(l) 

•  •  «  cshfl) 

•  .  «  lastcomm(l) 
«  •  •  cshfl) 

.  .  .  cdcfl) 

.  »  .  commfl) 

. . .  bk(<) 

.  ♦  «  socketf2) 

.  •  *  pipe(2) 

4  4  4  usetsfl) 


compact,  uncompact,  ccat  -  compress  and  uncompress  •  compactfl) 


comparator 


difffl) 


compare  two  files . . . cmpfl) 

compare  two  versions  of  an  SCCS  fife.  . . *  sccsdi^l) 

comparison.  . . diff3fl) 

compatibility  library  functions . introfSC) 

compiler . ccfl) 

compiler  . f77fl) 

compiler . * . pcfl) 

compiler . . . yacc(l) 

compiler  error  messages . errorfl) 

compiler-compiler . . . yacc(l) 

complete . cshfl) 

completion  of  process . waitfl) 

compress  and  uncompress  files,  and  cat  them.  .  •  .  .  .  compactfl) 
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hingmxB  - 

»  -  lilo;  8530  see  aerial 
cat  - 
test  - 
endif:  terminate 

if: 

while:  repeat  commands 

gettytab  -  terminal 
conhg  -  build  system 
tfconfig  - 

tip,  cti  - 

getpeemame  -  get  name  of 
socketpair  -  create  a  pair  of 
sbutdown  *  shut  down  part  of  a  full*dnptex 
accept '  accept  a 
connect  -  initiate  a 
listen  -  listen  for 


dcheek  -  file  system  directory 
ickeck  -  file  system  storage 
fsck  -  file  system 
cons  -  driver  for  Sun 
mkfs  - 
newfs  - 
mkproto  - 

deroff  -  remove  nroff,  troff,  tbl  and  eqn 
letriimit  -  control  maximum  system  resource 
vlimit  -  control  maximum  system  resource 
openpli  erase,  label,  line,  circle,  arc,  move, 

Is  -  list 

sigstack  -  set  and/or  get  signal  stack 
lockscreen  -  maintain  window 
newgrp,/  sk,  for,  case,  if,  while, break. 


arp  -  address  resolution  display  and 
fcntl  -  file 
ttd  -  network  disk 
iocti  - 
init  -  process 
getilimit,  setrlimit  - 
vlimit  - 
iemp  -  Internet 
dkio  -  generic  disk 
fcntl  >  file 
ipe  -  tine  printer 
top  -  Internet  Transmission 
lyslog,  openlog,  closelog  - 
vhangup  -  virtually  ** hangup**  the  current 
ip  -  Disk  driver  for  Interphaae  2180  SMD  Disk 
si  -  Driver  for  Sysgen  SC  4000  (Archive)  Tape 
td  -  Disk  driver  for  Adaptec  ST-S06  Disk 
xy  Disk  driver  for  Xytogics  SMD  Disk 
ecvt,  fevt,  gevt  -  output 
printf,  fprintf,  sprintf  -  formatted  output 
Bcanf,  fscanf,  sscanf  -  formatted  input 
tolower,  toaieii  -  character  classification  and 

units  - 
vswap  - 
dd- 
number  - 
rantib  - 
atof,  atoi,  atol  - 
localtime,  gmtime,  asetime,  timesone,  dysise  - 

htable  - 
getdate  - 
bed- 

htonl,  htons,  ntohl,  ntohs  - 
ching  -  the  book  of  changes  and  other 
rep  -  remote  file 
UUCP,  uulog  -  Unix  to  unix 
dd  -  convert  and 
cpio  - 
CP' 


Computer  version  of  the  game  hangman . 

comsat  -  biff  server.  . . . 

com  unications  driver.  . . 

concatenate  and  display.  . . 

condition  command . . . 

conditional . 

conditional  statement . 

conditionally . . . 

config  -  bnild  system  configuration  files . 

configuration  data  base. . 

confignration  files . .  ,  *  . 

configure  network  interface  parameters . 

connect  -  initiate  a  connection  on  a  socket . 

connect  to  a  remote  system . 

connected  peer.  . 

connected  sockets . 

connection . 

connection  on  a  socket . . . 

connection  on  a  socket . 

connections  on  a  socket . . . 

cons  -  driver  for  Sun  console . 

consistency  check.  . . 

consistency  check . 

consistency  check  and  interactive  repair . 

console . .  •  « 

construct  a  file  system . 

construct  a  new  file  system . 

construct  a  prototype  file  system . 

constructs.  *  *  •  «  «  •  . . 

consumption,  getrlimit . 

consumption . . 

cont,  point,  linemod,  space,  closepi  -  graphics/  *  .  .  . 

contents  of  directory.  . 

context . . 

context  until  *1ogin**. . 

continue,  cd,  eval,  exec,  exit,  export,  login . 

continue:  cycle  in  loop . 

control . 

control . 

control . . . 

control  device . 

control  initialisation . 

control  maximum  system  resource  consumption.  •  •  . 
control  maximum  system  resource  consumption.  .  »  . 

Control  Message  Protocol . 

control  operations . .  * 

control  options . 

control  program . 

Control  Protocol . 

control  system  log.  . 

control  terminal . 

Controller  . 

Controller.  . . 

Controllen.  . . 

Oontrollen . . 

conversion.  *  ♦  . . 

conversion . . . . . 

conversion . .  4  *  •  4.4  . . 

conversion  macros,  /isascii,  isgraph,  tonpper,  ..44 

conversion  program . . . 

convert  a  foreign  font  file . 

convert  and  copy  a  file . .  , 

convert  Arabic  numerals  to  English . 

convert  archives  to  random  libraries . . 

convert  ASCII  to  numbers . 

convert  date  and  time  to  ASCII,  ctime, . 

convert  NIC  standard  format  host  tables . 

convert  time  and  date  from  ASCII . 

convert  to  antique  media.  . . 

convert  values  between  host  and  network  byte  order.  » 

cookies . 

copy . 

copy . 

copy  a  file . 

copy  file  archives  in  and  out . 

copy  files . 


4  hangman(6) 

4  com8at(8C) 

4  fs(4S) 

4  cat(l) 

.  test(l) 

.  C8h(l) 

4  C8h(l) 

4  C8h(l) 

4  config(8) 

4  gcttytab(5) 

•  config(8) 

4  ifconfig(8C) 

4  connect(2) 

4  tip(lC) 

4  gctpeemame(2) 
4  socketpair(2) 

4  shutdown(2) 

4  accept(2) 

4  connect(2) 

•  Ii8ten(2) 

4  con8(4S) 

4  dcheck(8) 

4  icheck(8) 

4  f8ck(8) 

4  cons(4S) 

4  mkf8(8) 

•  newf8(8) 

4  mkproto(8) 

4  dero^l) 

4  getrlimit(2) 

4  vlimit  (3C) 

4  plot(3X) 

•  i»(i) 

4  sig8tack(2) 

4  lock8creen(l) 

.  *rp(8C) 

4  fcnt](2) 

4  nd(8C) 

4  toctl(2) 

4  init(8) 

4  getitimit(2) 

4  vlimit (3C) 

4  icmp(4P} 

4  dkio(<4S) 

4  fcntl(5) 

4  lpc(8) 

4  tcp(4P) 

4  8ysIog(3) 

4  vhangup(2) 

4  ipf4Sj 
4  st(4S) 

4  8d(4S) 

.  xy(4S) 

4  ccvt(3) 

4  printf(3S} 

4  scanf(3S) 

4  ctypc(3) 

4  nnit&(l) 

4  vswap(l) 

4  dd(l) 

4  number(6) 

4  ran]ib(l) 

4  atof(3) 

4  ctimc(3) 

4  htab]e(8) 

•  getdate(3) 

4  bcd(6) 

4  byteorder(3N) 

4  ching(6) 

4  rcp(lC) 

4  uucp(lC) 

4  dd(l) 

.  cpio(l) 

4  cp(l) 
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fork  -  create  a 
tee- 

eavecoie  -  «ave  a 
gcore  -  get 
feync  -  synchronixe  a  filers  in* 
functioBX.  xiDf 
eink, 
wc  -  irord 
xom  -  sum  and 


cpio  -  fomai  of 


analyxe  -  Virtual  UNIX  postmortem 
crash  -  what  happens  when  the  system 


fork  - 
tmpnam  - 
creat  - 

open  -  open  a  file  for  readinf  or  writinf ,  or 

fork  - 
socketpair  * 
ctafs  - 
socket  - 
mkstr- 
pipe- 
admin  - 
addbib  - 


catman  - 

nmask:  change  or  display  file 
nmuk  -  set  file 
cribbaf e  -  the  card  fame 


pxref  "  Pascal 
colcit  -  filter  nrofi  ontpnt  for 


syntax. 

locate  a  program  file  inctnding  aliases  and  paths  ( 

-  convert  date  and  time  to  ASCII. 

♦ip. 

vhangnp  -  virtually  “hangup”  the 
gethostid  -  get  nniqne  identifier  of 
gethostname,  sethostname  -  get/set  name  of 
hostnm  -  get  name  of 
hostid  -  print  identifier  of 
hostname  -  set  or  print  name  of 
jobs:  print 
sun  -  is 
vax  -  is 
sact  -  print 
sigaetmask  -  set 
whoami  -  display  effective 
chdir  -  change 
getcwd  -  get  pathname  of 
getwd  -  get 
motion. 

curses  -  screen  functions  with  “optimal” 
spline  -  interpolate  smooth 
continue: 
bs uncube  -  view  5- 
cron  -  clock 
inetd  -  internet  services 
Ipd  -  tine  printer 
routed  -*  network  routing 
It  -  command  script  for  auto^reboot  and 

ftpd  - 
lelnetd  - 
timed  - 
tftpd  - 


copy  of  this  process . .  *  . . 

copy  standard  output  to  many  files . .  ♦ 

core  -  foiniat  of  memory  image  file . 

core  dump  of  the  operating  system . 

core  images  of  tunning  processes . 

core  state  with  that  on  disk. 

cos,  tan,  asin,  acos,  atan,  atan2  -  trigonometric 

cosh,  tanh  -  hyperbolic  functions . 

count . .  •  •  * . 

count  blocks  in  a  file . .  •  •  «  . 

cp  *  copy  files . . . . 

cpio  -  copy  file  archives  in  and  out . .  * 

cpIo  *  format  of  cpio  archive . 

cpio  archive . 

cpp  -  the  C  language  preprocessor.  . 

crash  -  what  happens  when  the  system  crashes. 

crash  analyser . . . 

crashes. 

creat  -  create  a  new  file. 

create  a  copy  of  this  process . 

create  a  name  for  a  temporary  file.  . 

create  a  new  file . . . 

create  a  new  file . 

create  a  new  process . . . 

create  a  pair  of  connected  sockets . 

create  a  tags  file . . 

create  an  endpoint  for  communication . 

create  an  error  message  file  by  massaging  C  source, 
create  an  interprocess  communication  channel.  *  * 

create  and  administer  SCCS  filet . 

create  or  extend  bibliographic  database . 

create  the  cat  files  for  the  mannal . 

creation  mask . . . 

creation  mode  mask.  *  . . 

cribbage.  . . 

cribbage  -  the  card  game  cribbage . *  . 

cron  -  clock  daemon.  . . 

crontab  -  table  of  times  to  run  periodic  jobs.  «  • 

cross-reference  program . 

CRT  previewing . 

crypt  -  encode/decode . 

crypt,  set  key,  encrypt  -  DES  encryption . 

csb  -*  a  shell  (command  interpreter)  with  C-like 

csh  only),  which  -  . . . .  • 

ctags  -  create  a  tags  fife . 

ctime,  locattime,  gmtime,  asctime,  timeione,  dysise 

cu  -  connect  to  a  remote  system . .  « 

current  control  terminal . 

current  host . * . 

current  host.  .  •  . . .  «  «  •  • 

current  host.  . . . . 

current  host  system.  .  «  . . *  « 

current  host  system . . 

current  job  list . 

current  machine  a  sun  workstation . 

current  machine  a  vax . 

current  SCCS  file  editing  activity.  . 

current  signal  mask . 

current  username . . . 

current  working  directory. . .  .  .  . 

current  working  directory . . . 

current  working  directory  pathname . 

cunes  -  screen  functions  with  “optimal”  cursor 

cursor  motion . 

curve.  .  . . *  *  •  . . 

cycle  in  loop,  . . 

D  Sun  logo.  . . * . 

daemon . . . 

daemon.  . . 

daemon . 

daemon . 

daemons.  . . 

DARPA  Internet  File  Transfer  Protocol  server. 

DARPA  TELNET  protocol  server.  . 

DARPA  Time  server.  . 

DARPA  Trivial  File  Transfer  Protocol  server.  ♦  • 


.  •  fork(3P) 

.  .  Ml) 

«  «  core(5) 

•  .  savecore(8) 

.  ♦  gcorefl) 

•  •  f8ync{2) 

•  *  8in(3M) 

.  •  sinh^SM) 

.  •  eum(l) 

•  .  cp(l) 

«  •  cpio(l) 

•  *  cpioiS) 

«  .  cpio(5) 

•  •  cpiKl) 

•  «  crash(88) 

•  •  analyie(8) 

•  •  crashfSs) 

«  «  €reat(2) 

.  *  fork(3F) 

•  .  tmpnam(dC) 

•  »  creat(2) 

.  •  open(2) 

«  *  fork(2) 

•  .  80cketpaii(2) 

•  «  ctags(l) 

•  •  socket(2) 

•  .  mkstr(l) 

•  .  Pip«(2) 

•  •  admtn(l) 

•  ,  addbib(l) 

«  .  catman(8) 

«  »  C8h(l) 

•  «  uma8k(2) 

«  «  cribbageffi) 

•  •  cribbage(6) 

•  *  cron(8) 

«  •  crontab(5) 

.  *  pxref{l) 

.  •  colcrt(l) 


.  .  cryptfl) 

.  .  crypt(3) 

•  •  csh(l) 

»  •  which(l) 

.  •  ct^(l) 

«  »  ctimefS) 

«  «  tip(lC) 

•  *  vhangup(2) 

•  •  getho8tid(2) 

.  *  gethoBtname(2) 
.  •  ho8tnm(3F) 

.  «  hostid(l) 

.  *  ho8tname(l) 

•  .  esh(l) 

•  »  sunfl) 

•  •  vax(l) 

.  .  sact(l) 

«  .  8igsetiiU8k(2) 

•  .  whoami(l) 

«  •  chdir(2) 

•  •  gctcwd(3P) 

•  *  getwdfd) 

•  ♦  cur8e8f3X) 

«  .  cur8e8(3X) 

.  •  spiine(lG) 

•  «  csh(l) 

•  •  b8uncube(6) 

«  •  cron(8) 

•  «  inetd(8C) 

.  •  ipd(8) 

.  «  roated(8C) 

.  .  rc(8) 

.  .  ftpd(8C) 

«  *  telnetd(8C) 

.  ,  timed(8C) 

•  •  tftpd(8C) 
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eval:  re-<valtiate  shell 
~  display  call  ^aph  profile 
prof  -  display  profile 
ttys  -  terminal  initialisation 
Cettytab  -  terminal  configuration 
hosts  -  host  name 
networks  -  network  name 
phones  *  remote  host  phone  number 
printcap  ^  printer  capability 
protocols  -  protocol  name 
servers  -  inet  server 
services  -  service  name 
termcap  -  terminal  capability 
newaliases  -  rebuild  the 
ttytype  - 

dbminit,  fetchi  store^  delete,  fintkey,  nextkey  - 

oct  '  Central 
brk,  sbrk  ~  change 
null  - 

types  -  primitive  system 
addbib  -  create  or  extend  bibliographic 
roffbib  -  run  off  bibliographic 
sortbib  sort  bibliographic 
join  -  relational 
udp  -  Internet  User 
date  -  display  or  set  the 

gettimeofday,  settimeofday  -  get /set 
time,  hime  -  get 
fmtime,  aictime,  timeione,  dysiie  -  convert 
rdate  -  set  system 
getdate  -  convert  time  and 
touch  -  update 
idate,  itime  -  return 
data  base  subroutines. 


adb- 
dbx  “ 
od  “  octal, 

tp-. 

ciypt  -  encode/ 
uuencode,uudecode  -  encode/ 

chdir  -  change 
chsh  -  change 

kbd  -  keyboard  translation  table  format  and 
eqnchar  -  special  character 
close  - 

dbminit,  fetch,  store, 
ede  -  change  the  delta  commentary  of  an  SCCS 


delta  -  make  a 
ede  -  change  the 
rmdel  -  remove  a 
comb  -  combine  SCCS 
colordemot  - 
bdemos  - 
mesg  -  permit  or 
constructs, 
ciypt,  setkey,  encrypt  - 
whatis  - 

mailaddr  -  mail  addressing 
remote  -  remote  host 
close  -  delete  a 
dup,  dup2  -  duplicate  a 
getfstype,  setfsent,  endfsent  -  get  file  system 
getfd  -  get  the  file 
getdtablesise  -  get 
dc  - 
access  - 
access  - 
file- 

drum  -  paging 


data . 

data . . . . 

data . 

data . 

data  base . 

data  base . 

data  base . 

data  base . 

data  base . 

data  base . 

data  base . 

data  base.  •  . . * 

data  base . 

data  base  for  the  mail  aliases  file.  «  «  ,  «  •  . 

data  base  of  terminal  types  by  port . 

data  base  subroutines . 

Data  octal  serial  card . . 

data  segment  sise.  . 

data  sink . .  •  . 

datatypes.  «  . 

database . * . 

database.  . . 

database . . . 

database  operator.  . 

Datagram  Protocol . 

date . 

date  -  display  or  set  the  date . 

date  and  time,  . . 

date  and  time.  . . 

date  and  time  to  ASCII,  ctime,  localiime,  «  . 

date  from  a  remote  host . 

date  from  ASCII . . . 

date  last  modified  of  a  file . 

date  or  time  in  numerical  form . 

dbminit,  fetch,  store,  delete,  first  key,  nextkey  - 

dbx  -  debugger . 

dc  -  desk  calculator.  . .  . 

dcheck  -  file  system  directory  consistency  check. 

dd  -  convert  and  copy  a  file . 

debugger . 

debugger . 

decimal,  hex,  ascii  dump . 

DE^/mag  tape  formats . 

decode . . . 

decode  a  binary  file  for  transmission  via  mail, 
default:  catchall  clause  in  switch. 

default  directory. . 

default  login  shell . 

default  table . 

definitions  for  eqn . . . 

delete  a  descriptor  . 

delete,  firstkey,  nextkey  -  data  base  subroutines. 

delta.  . . *  «  . 

delta  -  make  a  delta  (change)  to  an  SCCS  file. 

delta  (change)  to  an  SCCS  file.  «  . . 

delta  commentary  of  an  SCCS  delta.  •  •  •  . 

delta  from  an  SCCS  file . 

deltas . 

demonstrate  Snn  Color  Graphics  Display.  «  « 
demonstrate  Sun  Monochrome  Bitmap  Display. 

deny  messages . 

dereff  -  remove  nroff,  troff,  tbi  and  eqn  •  «  « 

DES  enciyption . 

describe  what  a  command  is . 

description . . . 

description  file.  . . 

descriptor. . 

descriptor  . 

descriptor  file  entry  /getfsspec,  getfsfile,  *  . 
descriptor  of  an  external  unit  number.  «  ,  . 

descriptor  table  sixe.  44.  . . 

desk  calculator  >  ,  *  *  * . 

determine  accessability  of  a  file.  ...... 

determine  accessibility  of  file.  . 

determine  file  type . 

device . 


.  .  4  .  C5h(l) 

.44.  gprof(l) 

.  .  4  4  prof(l) 

4  *  4  *  ttya(6) 

4.44  gettytab(5} 

4  .  .  4  hosts(5) 

4.44  networks(5) 

•  4  4  4  phones(5) 

4444  printcap(5) 

4  4  4  4  protocols(5} 

4  4  4  4  8crvers(5) 

4  4  4  4  8ervice8(5) 

.  4  4  4  termcap(fi) 

4.44  newalia8e8(8) 

4  4  4  4  ttytype(5) 

4  4  4  4  dbm(3X) 

4.44  oct(4S) 

4.44  brk(2) 

4  4.4  null(4) 

•  4.4  types(S) 

•  4  4  4  addbib(l) 

4  4.4  roffbib(l) 

4  4  4  4  8ortbib(l) 

•4.4  joinfl) 

4  4  4  4  Udp(4P) 

•  4  4  4  date(l) 

4.44  date(l) 

4  4  4  4  gettimeofday(2) 
4  4  4  4  time(3C) 

4  4  4  4  ctime(S) 

4  4  4  4  rdate(8) 

.44.  getdate(3) 

4  4  4  4  touch(l) 

4  4  4  4  idate(3F) 

4  4.4  dbm(3X) 

4  4  4  4  dbx(l) 

4  4  4  4  dc(l) 

44.4  d€heck(8) 
4444  dd(l) 

4  4  4  4  adb(l) 

4  4.4  dbx(l) 

4  .  4  4  Od(l) 

4  4  4  4  tp(5) 

4  4  4  4  crypt(l) 

4  4  4  4  nnencode(lC) 

4  4  4  4  C8h(l) 

•  4  4  4  chdir(3P) 

4  4  4  4  ch8h(l) 

•  4.4  kbd(5) 

4  4.4  eqnchar(7) 
44.4  clo8e(2) 

4  4  4  4  dbm(3X) 

4  4  4  4  cdc(l) 

•  4  4  4  delta(l) 

4  4  »  4  de]ta(l) 
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4  4  4  4  comb(l) 
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4  4.4  ciypt(3) 

4.44  whatis(l) 

4  4  4  .  mailaddr(7) 

44.4  remote(S) 
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fold  -  fold  long  linos  for  finite  width  ontpnt 
ioctl  -  control 
sw&pon  -  ndd  &  swap 
swapott  -  specify  addition^ 

flmin,  Umax,  dfimin^ 
fimin,  fimax, 
package, 
dmesg  -  collect  system 
ratfor  -  rational  Fortran 


diff- 
diflS  -  3-way 

dir  -  format  of 
rm,  rmdir  -  remove  (nnlink)  files  or 
rmdir,  rm  -  remove  (unlink) 
cd  -  change  working 
chdir  -  change  current  working 
chdir  -  change  default 
chroot  -  change  root 
cd: change 
chdir:  change 

getcwd  -  get  pathname  of  cunent  working 
Is  -  list  contents  of 
mkdir-  make  a 
Bcandir,  alphasort  -  scan  a 
unclean  *-  uucp  spool 
dilf  -  differential  file  and 
dcheck  -  file  system 
unlink  -  remove 
unlink  remove  a 
mkdir  -  make  a 
rmdir  -  remove  a 
pwd  -  print  working 
readdir,  telldir,  seekdir,  rewinddir,  closedir  - 
getwd  -  get  current  working 
popd:  pop  shell 
pushd:  push  shell 
setquota  -  enable/ 
unhash: 

unset: 
bk  -  line 

-  synchronise  a  file’s  in-core  state  with  that  on 

nd  -  network 
dkio  -  generic 

ip  -  Disk  driver  for  Interphase  2180  SMD 
id  -  Disk  driver  for  Adaptec  ST-506 
xy  -  Disk  driver  for  Xylogici  SMD 
nd  -  network 
sd  - 

Controller,  ip  - 
xy- 

quota  -  manipulate 
df  -  report  free 
du  -  summarise 

-  reboot/halt  the  system  without  checking  the 

mount,  umount  -  mount  and 
error  -  analyse  and 
bdemos  -  demonstrate  Sun  Monochrome  Bitmap 
cat  -  concatenate  and 
cotordemos  -  demonstrate  Sun  Color  Graphics 
rain  -  animated  raindrops 
arp  address  resolution 
cal  - 
fprof- 
snake,  snscore  - 
vi  -  screen  oriented  (visual) 
whoami  * 
umask:  change  or 
head  - 

peifmon  -  graphical 
date  - 
prof  - 

worms  -  animate  wonna  on  a 


device . . . 

device . * . .  *  •  * 

device  for  interleaved  paging/swapping.  .  *  • 

device  for  paging  and  swapping.  . 

df  •  report  free  disk  space  on  file  systems.  .  * 
dflmax,  inmax  -  return  extreme  values.  *  •  « 
dflmin,  dfimax,  inmax  -  return  extreme  values, 
diag  -  General-purpose  stand-alone  utility  .  • 

diagnostic  messages  to  form  error  log . 

dialect.  «  * . 

diff  -  differential  file  and  directory  comparator. 
diffS  -  3-way  differential  file  comparison.  •  « 
differential  file  and  directory  comparator.  .  . 

differential  file  comparison . 

dir  -  format  of  directories . 

directories . 

directories . 

directories  or  files . • 

directory . 

directory . • 

directory . . 

directory.  •  •  «  . . 

directory.  . . 

directory . 

directory . 

directory.  •  •  . . .  •  «  «  * 

directory.  . . . 

directory . * . .  .  •  »  . 

directory  clean-up.  «  .  . . .  ♦  « 

directory  comparator . 

directory  consistency  check . .  .  .  « 

directory  entry . 

directory  entry . 

directory  file . 

directory  file.  . .  * . 

directory  name . . . 

directory  operations,  opendir, 

directory  pathname . .  •  •  « 

directory  stack . .  .  «  « 

directory  stack . 

disable  quotas  on  a  file  system. 

discard  command  hash  table . 

discard  shell  variables . 

discipline  for  machine-machine  communication. 

disk.  fs3mc  . .  * . 

disk  control . .  . . 

disk  control  operations . 

Disk  Controller.  ♦  .  ,  »  . . 

Disk  Controllers . . . . 

Disk  Contiollen . .  «  .  . 

disk  driver . 

Disk  driver  for  Adaptec  ST-506  Disk  Controllers. 
Disk  driver  for  Interphase  2180  SMD  Disk  .  • 
Disk  driver  for  Xytogics  SMD  Disk  Controllers. 

disk  quotas.  ,  * . * . 

disk  space  on  file  systems.  •  •  *  . . 

disk  usage . .  • 

disks,  fastboot,  fasthali  «  .  «  . . 

dismount  file  system.  . .  «  » 

disperse  compiler  error  messages . 

Display . 

display . . . . . 

Display.  •  •  .  * . 

display.  . . 

display  and  control.  . . 

display  calendar.  .  ,  . . . 

display  call  graph  profile  data.  •  . . 

display  chase  game . 

display  editor  based  on  ex . . 

display  effective  current  username . 

display  file  creation  mask.  «  . . 

display  first  few  lines  of  specified  files.  .  .  . 

display  of  general  system  statistics . 

display  or  set  the  date . 

display  profile  data. 

display  tenninal.  . . 


fo]d(l} 

ioctl(2) 

8waponf2l 

8wapon(8) 

df(i) 

rangefSF) 

rattge(3F) 

dia^Ss) 

dme8g(8) 

ratfo^l) 

diff(l) 

aiffd(l) 

diff(l) 

diff3(l) 

diifh) 

dii|5| 

rmdir(l) 

ed(l) 

chdir(2) 

chdir(3P) 

chroot(2) 

C8h(l) 

C8h(l) 

getcwd(3F) 

1.(1)  ^ 

mkdir(l) 

scandir(3) 

uuclea&(8C) 

diff(l) 

dcheck(8) 

untink(2) 

unlink(3F) 

mkdii(2) 

rrodir(2) 

pird(l) 

directoiy(3) 

gctwd(3) 

C8h(l) 


csh(l) 

setquota(2) 

cshll) 

csh(l) 

bk(4) 

fsync(2) 

nd(8C) 

dkio(4S) 

ip(4S) 

id(4S) 

xyf4S) 

nd(4P) 

id(4S) 

ip{4S) 

xy(4S) 

quota(2) 

df(i) 

do(l) 

fa8tboot(8) 

mount(8) 

error(l) 

bdemo8(6) 

c»t(l) 

cotordemo8(6) 

rain(6) 

arp(8C) 

c*l(l) 

Bprof(l) 

8Dake(6) 

vi(l) 

whoami(l) 

€sh(l) 

head(l) 

perfmon(l) 

date(l) 

prof(l) 

worin8(6) 
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tail  - 

hypot,  cabs  -  Euclidean 
error  log. 

refer  -  0iid  and  insert  literature  references  in 
troff  *  typeset  or  format 
w  -  who  is  on  and  what  they  are 
shutdown  >  shut 
shutdown  -  close 

graph- 

draw  -  interactive  graphics 
arithmetic  -  provide 
ar  *  Archive  1/4  inch  Streaming  Tape 
tm  -  tapemaster  1/2  inch  tape 
nd  -  network  disk 
pty  -  pseudo  terminal 
ft  -  f Hog  8530  see  serial  comunieations 

sd  -  Disk 
ip  -  Disk 
cons  - 
Controller  at- 
xy  -  Disk 

adjacenttcrseni  -  notify  the  window 
term  -  terminal 
term  -  terminal 


dump  -  incremental  file  system 
od  -  octal,  decimal,  hex,  ascii 

dumpfs  - 

dump,  dumpdates  -  incremental 
savecore  -  save  a  core 
kgmoB  -  generate  a 
dump, 

dnp, 

shutdown  -  shut  down  part  of  a  full* 
dup,  dup2  - 

ctime,  local  time,  gmtime,  aictime,  timetone, 


echo: 
echo  - 


end,  etext, 
vipw  - 

sact  -  print  current  SCCS  file 
ed  -  text 
ex,  edit  -  text 
Id  -  link 
aed  -  stream 

view  a  file  without  changing  it  using  the  vi  visual 
vi  -  screen  oriented  (visual)  display 
a.out  -  assembler  and  link 
whoami  -  display 
setregid  -  set  real  and 
setreuid  -  set  real  and 
vforic  -  spawn  new  process  in  a  virtual  memory 

grep, 

Insque,  remque  -  insert /remove 
soclim  - 

tektool  -  Tektronix  4014  terminal 

setquota  - 
uuencode  -  format  of  an 
crypt- 

mail,  uuencode, uudecode  - 
crypt,  setkey, 


display  the  last  part  of  a  file . 

distance . .  «  •  «  « 

dkio  -  generic  disk  control  operations . ^ 

dmesg  -  collect  system  diagnostic  messages  to  form 

documents . 

documents . 

doing . 

down  part  of  a  fnlMnplex  connection . 

down  the  system  at  a  given  time . 

draw  -  interactive  graphics  drawing . 

draw  a  graph . .  ,  .  . 

drawing . 

drill  in  number  facts . . . 

Drive . 

drive . 

driver.  ,4  * . 

driver.  . 

driver.  . .  • 

driver  for  Adaptec  ST*500  Disk  Controllers.  .  « 
driver  for  Interphase  2180  SMD  Disk  Controller. 

driver  for  Sun  console . 

Driver  for  Sysgen  SC  4000  (Archive)  Tape  •  •  • 
driver  for  Xylogics  SMD  Disk  Controllers.  .  «  « 
driver  of  the  physical  relationships  of  sexeens.  « 

driving  tables  for  nroff.  . 

driving  tables  for  nroff.  . 

drum  -  paging  device.  . 

du  -  summariie  disk  usage.  . 

dump . 

dump.  . . 

dump  -  incremental  file  system  dump . 

dump,  dumpdates  -  incremental  dump  format.  • 

dump  file  s^em  information . 

dumpfonnat . . . 

dump  of  the  operating  system . 

dump  of  the  operating  system^s  profile  buffers.  • 

dumpdates  -  incremental  dump  format . 

dumpfs  -  dump  file  system  information . 

dup,  dup2  -  duplicate  a  descriptor. . 

dup2  -  duplicate  a  descriptor . 

duplex  connection . 

duplicate  a  descriptor.  . 

dysise  -  convert  date  and  time  to  ASCII.  .  .  . 

ec  -  3Com  10  Mb/s  Ethernet  interface . 

echo  -  echo  arguments . 

echo  arguments . 

echo  arguments.  «...  * . 

echo:  echo  arguments . 

ecvt,  fevt,  gevt  -  output  conversion . 

ed  -  text  editor.  . . . 

edata  -  last  locations  in  program . 

edit  -  text  editor . 

edit  the  password  file . 

editing  activity . 

editor . 

editor.  . 

editor . 

editor . 

editor,  vi  -  . 

editor  based  on  ex . *  « 

editor  output.  «  *  . . 

effective  current  username.  . 

effective  group  ID.  . . 

effective  user  lD*s . .  , 

efficient  way . 

egrep,  fgrep  -  search  a  file  for  a  pattern.  ,  *  . 

element  from  a  queue.  . 

eliminate  .so^s  from  nroff  input . 

else:  alternative  commands . 

emulator  tool . 

en  -  Sun  3  Mb/s  experimental  Ethernet  interface. 

enable/disable  quotas  on  a  file  system . 

encoded  uuencode  file . 

encode/decode.  .  * . .  *  »  * 

encode/decode  a  binary  file  for  transmission  via 
enciypt  -  DES  encryption . 


tai)(l) 

hypot(3M) 

dkio(4S) 

dme8g(8) 

rcfcr(l) 

troff(l) 

*(i) 

shutdowii(2) 

shutdown(8) 

draw  (5) 

graph(lG) 

draw  (6) 

arithmetic(6) 

w(4S) 

tm('4S) 

itdH?) 

PW) 

n(4S) 

«d(4S) 

ip(4S) 

con8(4S) 

8t(4S) 

X3^4S) 

ad  jacentscreen8(I ) 

,term(5) 

tenD(5) 

dnim(4) 

dti(l) 

dump(8) 

od(l) 

dumpfs) 

dump(5) 

dumpfs(8) 

dump(5) 

8avccoie(8) 

kgmon(8) 

dump(5) 

dumpf5(8) 

dupf2) 

dup(2) 

8hutdown(2) 

dup(2) 

ctime(3) 

ec(4S) 

ecbo(l) 

C8h(l) 

echo(l) 

C8h(l) 

ecvt(3) 

ed(l) 

end(3) 

ex(l) 

vipw  (8) 

sact(l) 

ed(l) 

«x(l) 

ld(l) 

8ed(l) 

view(l) 

vi(l) 

a.out(6) 

whoamifl) 

8etregid(2) 

8etreuid(2) 

vfork(2) 

8rep(l) 

in8que(3) 

soelim(l) 

csh(l) 

tektool(l) 

en(4S) 

8etquota(2) 

uncacode(5) 

ctypt(l) 

uuencode(lC) 

crypt(3) 
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crypt,  8«tk«y,  encrypt  -  DES 
makekey  -  generate 

8CCB  -  front 
logout: 

/gctfaspec,  getfBfile,  getfstype,  aetfscnt, 
get^rent,  getcrgid,  getgmam,  Betgrent, 
getboBtbyaddr,  getkost  byname,  sethoBtent, 

getnetent,  getnetbyxddr,  getnetbyname,  Betnetent, 

socket  -  create  an 
getprotobynnmber,  getprotobyname,  setprotoent, 
getpwent,  getpwnid,  getpwnam,  setpwent, 
getservbyport,  getaervbyname,  setaervent, 

number  -  convert  Arabic  numerals  to 
xsend,  xget, 
alist  -  get 

endfsent  -  get  file  system  descriptor  file 
getgmam,  setgrent,  endgrent  -  get  group  file 
sethostent,  endhostent  -  get  network  host 
getnet byname,  setnetent,  endnetent  -  get  network 
setprotoent,  endprotoent  -  get  protocol 
getpwnam,  setpwent,  endpwent  -  get  password  file 
setservent,  endaervent  -  get  service 
ayslog  -  make  system  log 
unlink  -  remove  directory 
unlink  -  remove  a  directory 
execi,  execv,  execle,  exectp,  execvp, 

setenv;  set  variable  in 
environ  -  user 
printenv  -  print  out  the 
suntools  >  the  Suntoola  window 
taei  -  establish  terminal  characteristics  for  the 
getenv  -  value  for 
unsetenv:  remove 
getenv  get  value  of 
eqnchar  -  special  character  definitions  for 
deroff  -  remove  nroff,  troff,  tbl  and 


linemod,  apace,  closep)  -  graphics/  openpl, 
perror,  ays^errlist,  sys_ncrr, 
messages. 

dmesg  -  collect  system  diagnostic  messages  to  form 

mkatr  -  create  an 
error  -  analyse  and  disperse  compiler 
perror,  lys^erHisi,  sys.nerr,  ermo  -  syrtem 
perror,  gerror,  termo  -  get  system 
intro  -  introduction  to  system  calls  and 
eyacc  -  modified  yacc  allowing  much  improved 
spell,  spell  in,  spellont  -  find  spelling 
chase  -  Try  to 
environment,  tset- 
end, 

ec  -  $Com  10  Mb/s 
en  -  Sun  3  Mb/s  experimental 
hypot,  cabs  - 

for,  case,  if,  while, .,  break,  continue,  cd, 

esxpr  - 
eval:  re* 
history:  print  history 
-  screen  oriented  (visual)  display  editor  based  on 

Ipq  -  Bpool  queue 
/case,  if,  while,  .,  break,  continue,  cd,  eval, 

execute  a  file, 
exed,  execv, 
execi,  execv,  execle, 
Bticky  - 

excel,  execv,  execle,  execlp,  exeevp,  environ  - 

exeeve  - 


encryption.  . . 

encryption  key . 

end,  etext,  edata  -  last  locations  in  program . 

end  for  the  .SM  SCCS  subeystem . .  •  . 

end  session.  •  . . *  »  . 

end:  terminate  loop . . 

endfsent  -  get  file  system  descriptor  file  entry . 

endgrent  *  get  group  file  entry.  . . *  ,  . 

endhostent  -  get  network  host  entry,  gethostent,  •  •  • 

endif:  terminate  conditional . 

endnetent  -  get  network  entry . *  .  •  ,  . 

endpoint  for  communicatton . 

endprotoent  -  get  protocol  entry,  getprotoent, . 

endpwent  -  get  password  file  entry. . 

endaervent  ~  get  service  entry,  getservent,  . 

endsw:  terminate  switch.  *  .  •  . . 

English.  . . . . 

enroll  *  secret  mail . .  *  .  . . . 

entries  from  name  list . . . 

entry,  /getfsspec,  getfsfile,  getfstype,  setfsent . 

entry,  getgrent,  getgigid . . . 

entry,  gethostent,  gethostbyaddr,  gethostbyname,  •  .  * 

entry,  getnetent,  getnetbyaddr,  . 

«Btry.  /getprotobynumber,  getprotobyname . 

entry,  getpwent,  getpwnid . 

entry,  getservent,  getservbyport,  getservbyname,  .  .  . 

entry . 

entry . . . . . 

entry.  •  •  •  . 

environ  -  execute  a  file.  . .  •  * 

environ  -  user  environment . .  .  .  * 

environment . . 

environment . . . 

environment . 

environment.  •  . . .  •  ,  *  * 

environment . 

environment  name . .  • 

environment  variables.  . . 

environment  variables . 

eqi . 

eqn  constructs. . 

eqn,  neqn,  cbeckeq  -  typeset  mathematics . 

eqnchar  *  special  character  definitions  for  eqn . 

erase,  label,  line,  circle,  arc,  move,  cont,  point,  •  •  •  *  * 

crnio  -  system  error  messages.  «  . . 

error  -  analyse  and  dispene  compiler  error  . 

error  log.  . . 

error  message  file  by  massaging  C  source. 

error  messages . . . 

error  messaged . . . .  •  «  •  « 

error  messages.  •  «  •  «  . . 

error  numbers . 

error  recovery . .  «  •  . 

errors . . . 

escape  to  killer  robots.  •  . . 

establish  terminal  characteristics  for  the . 

etext,  edata  -  last  locations  in  program . 

Ethernet  interface . . . 

Ethernet  interface . . 

Euclidean  distance . 

eval,  exec,  exit,  export,  login,  newgrp,  read,/  sh . 

eval:  re-evaluate  shell  data . 

evaluate  arguments  as  an  expression . 

evaluate  shell  data . 

event  list . 

ex.  vi  ♦  . . . . . 

ex,  edit  -  text  editor . . . 

examination  program.  . . 

exec,  exit,  export,  login,  newgrp,  read,  readonly,/  .  •  , 

exec:  overlay  shell  with  specified  command . 

exed,  execv,  execle,  execlp,  exeevp,  environ  -  . 

exede,  execlp,  exeevp,  environ  -  execute  a  file.  .  .  .  «  « 

execlp,  exeevp,  environ  -  execute  a  file . 

executable  files  with  persistent  text . . 

execute  a  file.  . . . . 

execute  a  file . . 


crypt(3) 

makekey(8) 

end(3) 

8CC8(1) 

cshfl) 

cshfi) 

getf8ent(3) 

getgrent(3) 

gethostent(3N) 

C8h(l) 

getnetent(3N) 

socket(2) 

getprotoent(dN) 

getpwent(3) 

getservent(3N) 

csh(l) 

number(6) 

xfend(l) 

nli8t(3) 

getfsent(3) 

getgrent(3) 

gethostent(3N) 

getnetent(3N) 

getprotoent(3N) 

getpwent(3) 

getservent(3N) 

»y»log(l) 

unlinkf2) 

unlinkUP) 

cxecl(3) 

environ(5) 

€sh(l) 

environ(5) 

printen'^1) 

8untool8(l) 

t8et(l) 

geten^3) 

csh(l) 

getenv(3P) 

cqnchai(7) 

deroff(l) 

eqn(l) 

fqnchar(7) 

plot(SX) 

pciTor(3) 

erroi:(l) 

dmesgfS) 

mk8ti(l) 

enor(l} 

perrorfS) 

perror(3P) 

intro(2) 

«yacc(l) 

spell(l) 

cha8e(6) 

t8et(l) 

end(3) 

tc(4S) 

en(4S) 

hypot(3M) 

•Ml), 

cab(l) 

expr(l) 

cab(l) 

csb(l) 

Ti(l) 

ex(l) 

IpMl) 

8b(l) 

C8h(l) 

exedf3| 

exed(3) 

exed(3) 

8tick:^8} 

execl(3) 

execve(2) 
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^Unn  - 
system  - 
repeat: 
at  - 

laetcomm  -  sKosr  last  commaads 
aux  -  aaix  to  naix  command 
acct  - 
sleep  -  suspend 
sleep  -  suspend 
sleep  -  suspend 
monitor^  monstartnp,  moncontrol  -  prepare 

pxp  -  Pascal 
rexecd  -  remote 
profil  - 

pix  -  Pascal  interpreter  and 
file,  execi, 

execl»  execv,  execte.  exectp» 
link,  symlnk  -  make  a  link  to  an 
tnnefs  -  tune  np  an 

pending  output. 

/if,  while,  break,  continue,  cd,  evat,  exec, 

breaksw: 

break: 

logarithm,  power,  square  root. 

glob:  filename 
expand,  unexpand  - 
versa, 
en  -  Sun  3  Mb/s 

adventure  -  an 
frexp,  Idexp,  modf  -  split  into  mantissa  and 
exp,  log,  logic,  pow,  sqrt  - 
/while, :, .,  break,  continue,  cd,  evat,  exec,  exit, 

expr  -  evaluate  arguments  as  an 
re^comp,  rc_cxec  -  regular 
addbib  -  create  or 
getfd  -  get  the  file  descriptor  of  an 
strings,  xstr- 
recoveiy. 

ioinit  -  change 
tclese,  tread,  t write,  trewin.  tskipf,  t state  - 

functions. 

signal  -  simplified  software  signal 
sigvec  -  software  signal 
arithmetic  *  provide  drill  in  number 
pstat  -  print  system 
true, 

inet  -  Internet  protocol 
without  checking  the  disks, 
the  disks,  fastboot, 
abort  -  generate  a 
trpfpe,  fpecnt  -  trap  and  repair  fioating  point 

chmod, 

chown, 


ecvt, 

fopen,  freopen, 
ferror, 
inquiries. 

base  subroutines,  dbminit, 
bead  -  display  first 
fclose, 

bcopy,  bcmp,  biero, 
g«tc, 

stream,  getc.  get  char, 


execute  a  subroutine  after  a  specified  time.  . alarm(3F) 

execute  a  UNIX  command . *  «  .  ,  8y3tem(3F) 

execute  command  repeatedly . csh(l) 

execute  commands  at  a  later  time . .  .  at(l) 

executed  in  reverse  order.  . .  lastcomm(l) 

execution . uux(lC) 

execution  accounting  file . . . acct (5) 

execution  for  an  interval . sleepfl) 

execution  for  an  interval . sleep(3F) 

execution  for  interval . sleep(3) 

execution  profile . monitorfS) 

execution  profiler . P^p(f) 

execution  server.  * . rexecd(8C) 

execution  time  profile . profil(2) 

executor . pi^(l) 

cxecv,  execle,  ex  eel  p,  exeevp,  environ  -  execute  a  .  •  .  ,  execl(3) 

exeeve  -  execute  a  file . execve(2) 

exeevp,  environ  -  execute  a  file . execl(3) 

existing  file . . . link(3P) 

existing  file  system . . . tunefs(8) 

_exit  -  terminate  a  process . exitf2) 

exit  -  terminate  a  process  after  flushing  any . *  ex  it  (3) 

exit  -  terminate  process  with  status . exit(3F) 

exit,  export,  login,  newgrp,  read,  readonly,  set,/  . h(i) 

exit  from  switch . C8h(l) 

exit:  leave  shell.  . C8h(l) 

exit  while/foreach  loop . . C8h(l) 

exp,  log,  loglO,  pow,  sqrt  -  exponential . .  .  •  ♦  exp(3M) 

expand  argument  list . C8h(l) 

expand  tabs  to  spaces,  and  vice  versa . expand(l) 

expand,  unexpand  -  expand  tabs  to  spaces,  and  vice  .  «  expand(l) 

experimental  Ethernet  interface . en(4S) 

expire  -  remove  outdated  news  articles . expires) 

exploration  game . advent ure(6) 

exponent.  •  .  «  . . frexp(3) 

exponential,  logarithm,  power,  square  root . exp(3M) 

export,  login,  newgrp,  read,  readonly,  set,  shift,/ . h(l) 

expr  -  evaluate  arguments  as  an  expression . expi|l) 

expression . expr(l) 

expression  handler.  .  .  . . * . regex(3) 

extend  bibliographic  database . addbib(l) 

external  unit  number . getfd(3F) 

extract  strings  from  C  programs  to  implement  shared  .  •  X8tr(l) 
eyacc-  modified  yacc  allowing  much  improved  error  «  .  eyacc(l) 

f77  -  FORTRAN-77  compiler.  . f77(l) 

f77  I/O  initiatifation . ioinit(3F) 

f77  tape  I/O.  topen,  .  ^  . . topeD(3F) 

fabs,  floor,  ceil  -  absolute  value,  floor,  ceiling  .  »  «  .  «  floor(3M) 

facilities.  •  »  •  •  . . .  •  8ignal(3) 

facilities.  .  ,  . . sigvec(2) 

facts . arithmetic(6) 

facts . . . * . p8tat(8} 

false  ~  provide  truth  values . tnie(l) 

false,  true  -  provide  truth  values . false(l) 

family.  . . . . inet(4F) 

fastboot,  fasthali  -  reboot /halt  the  system  . fa8tboot(8) 

fasthalt  -  reboot/halt  the  system  without  checking  .  .  .  fast  boot  (8) 

fault . . . abort(3) 

faults.  «  «  ,  ^  . . trpfpe(3F) 

fbio  -  general  properties  of  frame  buffers.  . .  ,  fbio(4S) 

fchmod  -  change  mode  of  file.  .  •  . . chmod(2) 

f chown  '  change  owner  and  group  of  a  file  . €hown(2) 

fetose,  fflush  -  close  or  flush  a  stream. . fclo8e(3S) 

fenti  -  file  control . fcnt](2) 

fcntl  -  file  control  options . fcntl(5) 

fevt,  gevt  -  output  convenion . ccvt(3) 

fdopen  -  open  a  stream.  . . .  fopen(3S) 

feof,  clearerr,  fileno  -  stream  status  inquiries . feiTor(3S) 

ferror,  feof,  clearerr,  fileno  -  stream  status . ferror(3S) 

fetch,  store,  delete,  firstkey,  nextkey  -  data  . dbm(3X) 

few  lines  of  specified  files . head(l) 

fflush  -  close  or  flush  a  stream . fclose(3S) 

ffs  -  bit  and  byte  string  operations. . bstriiig(3) 

fg:  bring  job  into  foreground . csli(l) 

fgetc  -  get  a  character  from  a  logical  unit . getc(3F) 

fgetc,  getw  -  get  character  or  integer  from . gctc(3S) 
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get9,  fgeis  -  get  &  stiiiig  from  &  strcim . .  «  < 

grep,  ogrep,  fgrep  -  aearch  &  file  for  a  p^tiera . 

&cceB9  *  determine  ncceosibilit j  of  file . . . . . 

Jicce99  -  determine  nccesBnbility  of  n  file. . . . .  •  • 

ncci  -  execution  ncconnting  file.  . . .  *  . . 

chmod,  fchmod  -  cbnnge  mode  of  file. . . . . . 

chmod  -  chnnge  mode  of  n  file . .  •  «  * 

chown»  febown  -  tbnnge  owner  nnd  group  of  *  file. . . . .  «  *  *  « 

coInn  -  remove  coInmnB  from  n  file. . . . 

core  -  formnt  of  memory  izxuge  file.  . . 

cient  -  create  a  new  file.  «  . . 

aonree:  rexd  commanda  from  file . . . . . 

ctag9  *  create  a  tagi  file.  . . . . 

dd  ^  convert  and  copy  a  file. . . . 

delta  -  make  a  delta  (change)  to  an  SCCS  file. . .  «  «  ♦ 

exeev,  execte»  execlp,  exeevp,  environ  -  execute  a  file,  exed . . . 

exeeve  -  execute  a  file . .  •  «  «  . 

-  apply  or  remove  an  adviaoty  lock  on  an  open  file,  fiock  . 

fpr  -  print  Fortran  file . 

get  -  get  a  veieion  of  an  SCCS  file.  . . . . 

group -group  file.  «  «  . . .  .  . . 

link  -  make  a  bard  link  to  a  file. . . . . . 

link,  symink  -  make  a  link  to  an  exiBting  file . . . 

mkdir  -  make  a  directory  file . 

mknod  -  make  a  specif  file.  •  •  . . . . 

mknod  -  build  apeciai  file . * . 

more,  page  -  browae  tbrougb  a  text  file.  . . . 

-  rebuild  tbe  data  base  for  tbe  mail  aliues  file,  newaliasei  . 

open  a  file  for  reading  or  writing,  or  create  a  new  file,  open  -  . . . . . 

pasiwd  -  password  file . 

prs  -  print  an  SCCS  file. . . . .  •  . 

remote  -  remote  host  description  file . . . .  . . 

rename  -  change  tbe  name  of  a  file. . 

rename  -  rename  a  file. . 

rev  -  reverse  lines  of  a  file. . 

rmdel  -  remove  a  delta  from  an  SCCS  file.  •  «  . . 

rmdir  -  remove  a  directory  file . 

iccidiff  *  compare  two  versions  of  an  SCCS  file . . . 

iccefite  -  format  of  SCCS  file. . . . 

site  -  site  of  an  object  file . . 

printable  strings  in  an  object,  or  other  binary,  file,  itrinp  -  find  . .  «  •  •  * 

sum  -  torn  and  count  blocki  in  a  file . . 

■ymlink  -  make  symbolic  link  to  a  file . .  «  « 

tail  -  display  tbe  last  part  of  a  file . 

tmpnam  -  create  a  name  for  a  temporary  file.  *  •  •  . . .  *  •  « 

touch  -  update  date  last  modified  of  a  file. . .  .  «  . . 

unget  -  undo  a  previous  get  of  an  SCCS  file . * . . . *  * 

uniq  -  report  repeated  lines  in  n  file . .  •  .  •  » 

uuencode  -  format  of  an  encoded  unencode  file. . . 

val  -  validate  SCCS  file. . . . 

vipw  -  edit  the  password  file . 

vswap  -  convert  a  foreign  font  file . 

write,  wiitev  -  write  on  a  file. . * . . . .  *  •  • 

file  -  determine  file  type . 

dit  -  differential  file  and  directory  comparator.  . 

cpio  -  copy  file  archives  in  and  out.  «  .  .  . . . . 

mkitr  -  create  an  error  message  file  by  massaging  C  source . *  . . 

diffS  -  3*way  differential  file  comparison . .  * 

fentl  -  file  control . . 

fcntl  -  file  control  options . * . . 

rep  -  remote  file  copy.  •  . . .  » 

umask:  change  or  display  file  creation  mask . . . 

umask  -  set  file  creation  mode  mask . 

getfd  -  get  tbe  file  descriptor  of  an  external  unit  number. . 

sact  -  print  cunent  SCCS  file  editing  activity . . . 

setfsent,  endfsent  -  get  file  system  descriptor  file  entry,  /getfsspec,  getfsfile,  getfstype . 

getgigid,  getgmam,  setgrent,  endgrent  -  get  group  file  entry,  getgrent,  .  .  * . .  , 

getpwnam,  setpwent,  endpwent  -  get  password  file  entry,  getpwent,  getpwuid . 

grep,  egrep,  fgrep  -  search  a  file  for  a  pattern . 

open  -  open  a  file  for  reading  or  writing,  or  create  a  new  file.  . 

newsrc  -  information  file  for  readnews(l)  and  cbecknews(l) . .  ♦  «  •  « 

aliases  -  aliases  file  for  sendmatl . .  . . . 

uuencode, uudecode  -  encode/decode  a  binary  file  for  transmission  via  mail . 

ar  -  archive  (library)  file  format . 

tar  -  tape  archive  file  format . 

which  -  locate  a  program  file  including  aliases  and  paths  (esh  only) . 


get8(SS) 

acces8f2) 

acces8(3P) 

acci(5) 

chmodf2) 

chmod(3F) 

chowD(2) 

colnnfl) 

core(5) 

creat(2) 

tsh(l) 

rtagB(l) 

dd(l) 

dcH^l) 

exed(3) 

execve(2) 

lock(2) 

Si. 

group(6) 

link(2) 


link(3P) 

mkdir(2) 

mknodf2) 

mknod(8) 

more(l) 

newalia6e8(8) 

opeB(2) 

pa89wd(5) 

pre(l) 

remote(S) 

rename(2) 

rename(3P) 

rmdelfl) 


rmdi^2) 

i€C8diff(l) 

icesfileffi) 

string8(l) 

snm(l) 

tymlink(2) 

tmpnam(3C) 

touch(l) 

nnget(l) 

uniq{l) 

nuencode(G) 

val(l) 

Tipw(8^ 

vswap(l) 

write(2) 

file(l) 

diff(l) 

cpio(l) 


rcp(lC) 

C8h(l) 

uma8k(2) 

getfd(3F) 

sact(l) 

getf8ent(S) 

getgrent(3) 

getpwe]it(3) 

8rep(l) 

open(2) 

new8rc(S) 

a!ia8e8(6) 

uuencode(lC) 

ar(5) 

tar(5) 

which(l) 
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fsplit  -  split  a  mniti-rootiae  Fotintn  file  into  individual  files . fsp]it(l) 

split  -  split  a  file  into  pieces . 8plit(l) 

pmex^ge  ~  pascal  file  merger.  . pmerge(l) 

mktemp  -  make  a  unique  file  name . mktemp(3) 

(seek,  ftell  -  reposition  a  file  on  a  logical  unit . fseek(3F) 

stat,  Istat,  fstat  -  get  file  status . 8tat(2} 

mkfs  -  construct  a  file  system.  . . mkf8(8) 

mkproto  -  construct  a  prototype  file  system . . . mkproto(8) 

mounts  umount  -  mount  or  remove  file  system . . . momit(2) 

mount,  umount  -  mount  and  dismount  file  system . . . mount(8) 

newfs  -  construct  a  new  file  system . . . newfs(8) 

setquota  -  enable/disable  quotas  on  a  file  system . 8etquota(2) 

tunefs  -  tune  up  an  existing  file  system . tunef3(8) 

repair  fsck  -  file  system  consistency  check  and  interactive . fsck(8) 

getfsfile,  getfstype,  setfsent,  endfsent  -  get  file  system  descriptor  file  entiy.  /getfsspec . getfsent(3) 

dcheck  -  file  system  directory  consistency  check . dcheck(8) 

dump  -  incremental  file  system  dump . dump(8) 

hier  -  file  system  hierarchy . hier(7) 

dumpfs  **  dump  file  system  information.  . . .  .  «  •  dumpfs(8) 

quot  -  summarise  file  system  ownership . quot(8) 

restore  -  incremental  file  system  restore . restores) 

icheck  -  file  system  storage  consistency  check . icheck(8) 

mtab  -  mounted  file  system  table . iiitab(5) 

fs,  inode  -  format  of  file  system  volume . *  «  «  *  . . f8(5) 

df  -  report  free  disk  space  on  file  systems . df(l) 

ntime  -  set  file  times . otime(3C) 

utimes  -  set  file  times . . . .  »  «  •  utimes(2) 

uusend  -  send  a  file  to  a  remote  host . . . .  *  uu8end(lC) 

truncate,  ftruncate  -  truncate  a  file  to  a  specified  length . tnincate(2) 

ftp  -  file  transfer  program . ftp(lC) 

ftpd  -  DARPA  Internet  File  Transfer  Protocol  server . . . ftpd(8C) 

tftpd  DARPA  Trivial  File  Transfer  Protocol  server . tftpd(8C) 

file  -  determine  file  type.  •  •  * . .  *  «  * . * 

editor,  vi  -  view  a  file  without  changing  it  using  the  vi  visual . view(l) 

basename  -  strip  filename  affixes . basename(l) 

glob:  filename  expand  argument  list . csh(l) 

ferror,  feof,  clearerr,  fileno  -  stream  status  inquiries . feiroi^SS) 

admin  -  create  and  administer  SCCS  files . .  admin(l) 

checknr  -  check  nroff/troff  files . checknr(l) 

emp  -  compare  two  files . . . cmp(l) 

comm  -  select  or  reject  lines  common  to  two  sorted  files . comm(l) 

config  -  build  system  configuration  files . config(8) 

cp  -  copy  files . cp(l) 

find  -  find  files . find(l) 

split  a  multi-rontine  Fortran  file  into  individnal  files,  fsplit  - . f8plit(l) 

had  -  display  fint  few  lines  of  specified  files . head(l) 

install  -  install  files . install(l) 

MAKEDEV  -  make  system  special  files . .  makede^S) 

mv  >  move  or  rename  files . mv(l) 

news  -  USENET  network  news  article,  utility  files . . . new8{5) 

rmdir,  rm  -  remove  (unlink)  directories  or  files . . . rmdi^l) 

sort  -  sort  or  merge  files . sort(t) 

tee  -  copy  standard  output  to  many  files . tee(l) 

what  -  identify  the  version  of  files . . . what(l) 

compact,  nncempaci,  cat  -  compress  and  nneempresi  files,  and  cat  them.  . compact(l) 

intro  -  introduction  to  special  files  and  hardware  support . .  intro(4) 

caiman  -  create  the  cat  files  for  the  manual . .  catman(8) 

fsync  -  synchronise  a  filers  in-core  state  with  that  on  disk . f8ync(2) 

rm,  rmdir  -  remove  (unlink)  files  or  directories . nn(i) 

pr  print  fi(e(s),  possibly  in  multiple  columns . pr(l) 

sticky  -  executable  files  with  persistent  text . 8ticky(8) 

fstab  -  static  information  about  tbe  filesystems . .  f8iab(5) 

colcrt  -  filter  nroff  output  for  CRT  previewing . colcrt(l) 

col  -  filter  reverse  paper  motions . . . col(l) 

plot  -  graphics  filten . plot(lG) 

find -find  files.  . . fiDd(l) 

refer  -  find  and  insert  literature  references  in  documents.  •  .  .  refe^l) 

find  -  find  files.  . . fiud(l) 

look  -  find  lines  in  a  sorted  list.  . . . look(l) 

man  -  print  out  manual  pages;  find  manual  information  by  keywords . man(l) 

ttyname,  isatty,  ityslot  -  find  name  of  a  terminal . ttyname(3) 

ttynam,  isatty  -  find  name  of  a  terminal  port . ttyiiam(3F) 

lorder  -  find  ordering  relation  for  an  object  library . lorder(l) 

binary,  file,  strings  -  find  printable  strings  in  an  object,  or  other  . strings(i) 

inverted  index  to  a  bibliography  .br  iookbib  -  find  references  in  a  bibliography,  indxbib  -  make  ...  indxbib(l) 

spell,  spcllin,  spellout  -  find  spelling  errors . 8pell(l) 
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fold  -  fold  long  liaes  for 
he&d  -  dispUy 
dbminit,  fetch,  Hore,  delete, 
fieb  -  play  *‘Go 

valnee.  flmitt, 
extreme  valtiee. 
trpfpo,  fpeciit  -  trap  and  repair 
fptype  -  check  a 
islnf,  isnan  -  teat  for  indeterminate 
open  file, 
functions,  fabs, 
fabi,  floor,  ceil  <*  absolute  value, 

fclose,  flioih  -  close  or 
flush  - 

exit  -  teiminate  a  process  after 

device, 
fold  - 

vswap  -  convert  a  foreign 
vfont  - 

break:  exit  while/ 

fg:  bring  job  into 
vswap  -  convert  a 


idate,  (time  -  return  date  or  time  in  numerical 
dmesg  -*  collect  system  diagnostic  messages  to 
ar  -  archive  (libraiy)  file 
dump,  dumpdates  -  incremental  dump 
tar  -  tape  archive  file 
kbd  -  keyboard  translation  table 
indent  -  indent  and 
troff  -  typeset  or 
htable  -  convert  NIC  standard 
gettable  -  get  NIC 
uuencode  - 
cpio  - 
dir- 
fs,  inode  - 
core- 
sccsflle  - 
tbi- 

tp  -  DEC/mag  tape 
vfont  -  font 
seanf,  fscanf,  sscanf  - 
printf,  fprintf,  sprintf  - 
fmt  -  simple  text 
nroff  -  text 
ms  -  text 
me  -  macros  for 
ratfor  -  rational 
fpr  -  print 
fsptit  -  split  a  multi-routine 
intro  -  introduction  to 
putc,  fpute  -  write  a  character  to  a 
f77- 
adage. 
trpfpe, 

printf, 

unit,  putc, 
putc,  putchar, 
puts, 

bw  -  Sun  black  and  white 
fbio  -  genera)  properties  of 

df*-  report 
allocator  malloc, 
fopen, 
exponent, 
from  -  who  is  my  mail 


finite  width  ontput  device.  . . . 

first  few  lines  of  specified  files.  «  •  . . 

firstkey,  nextkey  -  data  base  subroutines. 

Pish” . 

fish  -  play  ^*Go  Fish”.  . . . . 

flmax,  dflmin,  dflmax,  inmax  -  return  extreme . 

flmin,  flmax,  dflmin,  dflmax,  inmax  -  ntum . 

floating  point  faults . 

floating  point  number.  . . 

floating  point  values . . . 

flock  -  apply  or  remove  an  advisory  lock  on  an . 

floor,  ceil  -  absolute  value,  floor,  ceiling  •  .  . . 

floor,  ceiling  functions . 

flush  -  flush  ontput  to  a  logical  unit . .  «  •  •  « 

flush  a  stream . 

flush  output  to  a  logical  unit.  . . .  « 

flushing  any  pending  output.  «  «  •  . . 

fmt  -  simple  text  formatter.  . 

fold  -  fold  tong  lines  for  finite  width  output  . 

fold  long  lines  for  finite  width  output  device . 

font  file . 

font  formats . * . 

fopen,  freopen,  fdopen  -  open  a  stream.  •••••••» 

foreach  loop . 

fo  reach:  loop  over  list  of  names . 

foreground.  .  «  . . 

foreign  font  file.  . * . 

fork  -  create  a  copy  of  this  process . 

fork  -  create  a  new  process . .  • 

form.  •  «  . . 

form  error  log . . . 

format . .  • 

format.  .  •  «  ,  . . .  .  .  « 

format.  . . .  «  »  • 

format  and  default  table . . 

format  C  program  source . 

format  documents . . . . 

format  host  tables.  •  •  •  * . 

format  host  tables  from  a  host . 

format  of  an  encoded  uuencode  file . 

format  of  cpio  archive . 

format  of  directories.  •  •  «  »  . . 

format  of  file  system  volume . .  «  •  • 

format  of  memory  image  file . .  «  «  •  • 

format  of  SCCS  file.  . . . . 

format  tables  for  nroff  or  troff. . . 

formats.  . . . . 

formats . .  ♦  •  • 

formatted  input  conversion.  . . . 

formatted  output  conversion . . 

formatter. . . 

fonnatting  and  typesetting . .  •  •  » 

formatting  macros . .  , 

formatting  papen.  •  •  .  * . .  *  , 

Fortran  dialect . *  « 

Fortran  file.  . . . . 

Fortran  file  into  individual  files . . 

FORTRAN  library  functions.  .  . . . 

FORTRAN  logical  unit.  «  ♦  •  . . .  *  •  «  « 

FOR  TRAN-77  compiler.  . 

fortune  -  print  a  random,  hopefully  interesting,  •  *  *  • 
fpecnt  -  trap  and  repair  floating  point  faults.  .  .  «  •  . 

fpr  -  print  Fortran  file . *  ,  .  ,  . . 

fprintf,  sprintf  -  formatted  ontput  conversion.  «  *  «  «  • 

fptype  -  check  a  floating  point  number . 

fpute  -  write  a  character  to  a  FORTRAN  logical  •  •  •  . 
fpute,  putw  -  put  character  or  word  on  a  stream.  •  •  • 

fputs  -  put  a  string  on  a  stream . 

frame  buffer . . . . 

frame  buffers . .  «  •  •  « 

fread,  fwrite  ^  buffered  binary  input/output . 

free  disk  space  on  file  systems . . 

free,  realloc,  calloc,  efree,  atloca  -  memory 

freopen,  fdopen  -  open  a  stream.  . . 

frexp,  Idexp,  modf  -  split  into  mantissa  and  ••»••• 
from?.  . . . . . 


fold(l) 

head(l) 

dbm(SX) 

fish(6) 

fl8h(6) 

rangef3F) 

range(3F) 

tipfpe(3F) 

fptype(3P) 

i8inf(3) 

flock(2) 

floor(3M) 

floor\3M) 

flush(3F) 

fclo8e($S) 

flu8h(3F) 

exit(3) 

fmt(l) 

fold(l) 

fotd(l) 

V8wap(l) 

vfont(5) 

fopen(3S) 

C8h(l) 

C8h(l) 

csh(l) 

V8wap(l) 

fork(3P) 

fork(2) 

tdai^SF) 

dme8g(8) 

*i<6) 

dump(5) 

tM(5) 

kbd(fi) 

indent(l) 

tioff(i) 

htable(8) 

gettable(8C) 

uuencode{5) 

cpio(5) 

dix(^ 

f»(5) 

core(5} 

sccsfilqS) 

tbl(I) 

lp(5) 

vfont(5) 

scanf(3S) 

printf(3S) 

fmt(l) 

nro^l) 

ratfoT(l) 

fpr(l) 

f8plit(l) 

intro(3P) 

putcl^F) 

foitune(6) 

trpfpe(3F) 

fpr(l) 

printf(3S) 

fptype(3F) 

putefSF) 

putefSS] 

putsfSS) 

bw(4S) 

fbio(4S) 

fread(3S) 

m 

maltoc(3) 

fopen(3S) 

frexp(3) 

from(l) 
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8CC3  - 

8c&nf, 

interactive  repair. 

unit. 

individual  files. 

stat,  Istat, 
that  on  disk, 
fseek, 
fseek, 
time, 


server. 

imneate, 

shutdown  -  shut  down  part  of  a 
gamma  -  tog  gamma 
fabs,  floor,  ceil  -  abaointe  value,  floor,  celling 
intro  -  introduction  to  library 
intro  *  introdnetion  to  compatibility  library 
intro  -  introduction  to  FORTRAN  library 
intro  introduction  to  mathematical  library 
intro  -  introdnetion  to  network  library 
jO,  jl.  jn,  yO,  yl,  yn  -  beosd 
cos,  tan,  asin,  acos,  atan,  atan2  -  tngonometric 
sink,  cosh,  tank  -  hyperbolic 
cunes '  screen 
fiead, 

adventure  -  an  exploration 
monop  -  Monopoly 
snake,  snscore  -  display  chase 
trek  -  trekkie 
worm  -  Play  the  growing  worm 
canfield,  cfocores  -  the  solitaire  card 
ctibbage  -  the  card 
hangman  -  Computer  version  of  the 
backgammon  ~  the 
boggle  -  play  the 
wump  -  the 

gamma  -  log 

itom,  madd,  msub,  mult,  mdiv,  min,  moot,  pow. 


ecvt,  fevt, 
buffers,  kgmon  - 
abort  - 
adbgen  - 
makekey  - 
ncheck  - 

rand,  srand  -  random  number 
lex  - 

/initstate,  setstate  -  better  random  number 
random  number  generator,  routines  for  changing 

dkio  ** 
perror, 


Integer  from  stream, 
from  stream,  getc, 
directory. 


getgid, 


get  Old, 
unit  number 

setfsent,  endfsent  -  get  file  system  descriptor/ 
file  system  descriptor  file/  getfsent,  gctfsspec, 
-  get  file  system  descriptor  file/  getfsent, 
descriptor  file/  getfsent,  getfsspec,  getfsfile, 

getuid, 

get  group  file  entry, 
file  entry,  getgrent, 


front  end  for  the  .SM  SCCS  subsystem . 

fs,  inode  -  format  of  file  system  volume . 

fscanf,  sscanf  -  formatted  input  conversion, 
fsck  -  file  system  consistency  check  and  .  .  .  « 

fseek,  ftell  -  reposition  a  file  on  a  logical  •  .  . 

fseek,  ftell,  rewind  -  reposition  a  stream.  •  .  . 

fsplit  -  split  a  multi-routine  Fortran  file  into  «  . 

fstab  -  static  information  about  the  filesystems. 

fstat  -  get  file  status . 

fsync  -  synchronise  a  filers  in-core  state  with  .  . 

ftell  -  reposition  a  file  on  a  logical  unit . 

ftell,  rewind  -  reposition  a  stream . 

ftime  -  get  date  and  time . 

ftp  -  file  transfer  program . 

ftpd  -  DARPA  Internet  File  Transfer  Protocol  . 
ftruncate  -  tmneate  a  file  to  a  specified  length. 

fall- duplex  connection . 

function.  *  * . 

functions . . 

fnnetions . 

functions . . . 

functions . .  «  . 

functions . 

functions . 

fnnetions . . 

functions,  sin, . 

functions . 

functions  with  ^^optimaF'  cunor  motion.  •  •  » 

fwrite  -  buffered  binary  inpnt/outpnt . 

game . .  »  «  »  , 

game . 

game . 

game . 

game . 

game  canfield.  . . 

game  cribbage . 

game  hangman . 

game  of  backgammon,  .  «  . 

game  of  boggle . 

game  of  hunt-the-wnmpns . 

gamma  -  log  gamma  function . 

gamma  function . 

ged,  rpow  -  multiple  precision  integer  arithmetic, 
gcore  -  get  core  images  of  running  processes.  «  . 

gevt  -  output  conversion . 

generate  a  damp  of  the  operating  system's  profile 

generate  a  fault.  . 

generate  adb  script . 

generate  encryption  key.  «  •  . . 

generate  names  from  i-numbers . 

generator.  . . 

generator  of  lexical  analysis  programs . 

generator;  routines  for  changing  generators.  .  • 
generaton.  /srandom,  initstate,  setstate  -  better 

generic  disk  control  operations . .  , 

gerror,  iermo  -  get  system  error  messages.  *  .  « 
getarg,  iaige  -  return  command  line  arguments, 
getc,  fgetc  -  get  a  character  from  a  logical  unit, 
getc,  getchar,  fgetc,  getw  -  get  character  or  .  . 
getchar,  fgetc,  getw  -  get  character  or  integer 
getewd  -  get  pathname  of  current  working  »  • 
getdate  -  convert  time  and  date  from  ASCII. 

getdtablesiie  ~  get  descriptor  table  sire . 

getegid  -  get  group  identity . .  «  .  .  . 

getenv-  get  value  of  environment  variables.  .  • 

getenv  -  value  for  environment  name . 

geteuid  -  get  user  identity . 

getfd  -  get  the  file  descriptor  of  an  externa]  .  , 
getfsent,  getfsspec,  getfsfile,  getfstype,  •  ,  .  « 
getfsfile,  getfstypCj  setfsent,  endfsent  -  get  ♦  *  . 
getfsspec,  getfsfile.  getfstype,  setfsent,  endfsent  . 
getfstype,  setfsent,  endfsent  -  get  file  system  *  . 
getgid  -  get  user  or  group  ID  of  the  caller.  .  *  , 

getgid,  getegid  -  get  group  identity.  . 

getgrent,  getgrgid,  getgrnam,  setgrent,  endgrent  - 
getgrgid,  getgrnam,  setgrent,  endgrent  -  get  group 


•  *  *  ♦  sccs(l) 

....  fs(5) 

•  *  «  .  8canf(3S) 

.  .  »  .  f8ck(8) 

•  .  .  •  f3cek(3F) 

.  .  ,  .  f8eek(3S) 

.  .  •  .  fsp[it(l) 

«  •  «  .  fstab(5] 

«  »  «  •  8tat(2) 

.  .  .  .  fsync(2) 

«  *  «  *  f8eek(3F) 

«...  fseek(3S) 

.  .  «  .  time(3C) 

.  .  .  .  ftp(lC) 

,  .  .  .  ftpd(8C) 

.  .  .  .  truncate(2) 

.  «  .  .  8hutdown(2) 

.  .  .  .  gamma(3M) 

.  .  «  «  fioor(dM) 

.  .  .  .  introfS) 

.  .  •  «  introfSC) 

.  «  •  «  intro(3F) 

.  .  .  •  intro(3M) 

.  .  •  .  jntro(3N) 

....  iO(3M) 

.  «  .  «  siu(3M) 

•  «  .  .  sinh(3M) 

.  •  .  .  cur8e8(3X) 

....  fread(3S) 

.  *  •  .  advent  ure(6) 

.  .  .  •  monop(6) 

.  .  .  .  8nake(6) 

.  .  .  .  trek(6) 

.  .  .  .  wonii(6) 

.  .  .  .  canfield(6) 

«  .  .  .  cribbage(6) 

.  .  «  .  hangxnan(6) 

.  .  .  .  backgammo&(6) 
.  .  .  .  boggle(6) 

,  .  .  .  wump(6) 

.  .  .  •  gammaf3M) 

.  •  .  .  gamma(3M) 

«  .  .  .  mp(3X) 

.  .  .  .  gcore(l) 

,  •  .  •  ecvt(3) 

.  .  .  kgmon(8) 

.  .  .  .  abort(3) 

.  .  .  .  adbgen(8) 

.  .  .  .  makekey(8) 

.  .  «  »  ncheck(8) 

.  .  «  •  rand(3C) 

. . . .  i«(i) 

.  .  •  .  random(3) 

.  .  «  random(3) 

•  •  .  .  dkio(4S) 

.  .  .  .  perror(3F) 

.  .  .  .  getarg{3F) 

.  .  .  .  gctc(3F) 

•  «  .  .  getc(3S) 

.  .  .  .  gctc(3S) 

.  .  .  .  getcwd(3F) 

.  .  .  •  gctdatc{3) 

«  »  .  .  getdtab]e8ixe(2) 

.  .  .  .  getgid(2) 

.  .  .  .  gctcnvf3F) 

.  .  .  .  getcnv{3) 

.  .  ,  «  getttid(2) 

.  .  .  .  getfd(3F) 

.  ,  .  .  getfaent(3) 

.  .  .  .  getfaent(3) 

.  .  .  .  getf8ent(3) 

.  .  ,  .  getfsent(3) 

.  .  .  .  getuid(3F) 

.  .  .  .  getgid(2) 

.  .  .  getgrent(3) 

.  .  .  gctgrent(3) 
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entiy.  getgrent,  getsrsid, 

endhofftent  -  get  network  host  entry,  getkoetent, 
network  host  entry,  gethoatent,  gethoatby&ddr, 
aethoatent,  endboatent  -  get  network  boat  entry. 

boat. 

timer. 


get  network  entry,  getnetent, 
entry,  getnetent,  getnetbynddr, 
endnetent  -  get  network  entry. 

irgv. 


getpid, 
Bcbednling  priority, 
protocol  entry,  getprotoent,  getprotobynumber, 
endproioent  -  get  protocol  entry,  getprotoent, 
aetprotoent,  endprotoent  -  get  protocol  entry. 

get  pnaaword  file  entry, 
entry,  getpwent,  getpwuid, 
pnaaword  file  entry,  getpwent, 
resource  consumption. 

utilisation. 

Bcrvice  entry  getaervent,  getaervbyport, 
endaervent  -  get  aervice  entry,  getaervent, 
aetaervent,  endaervent  -  get  aervice  entry. 

aocketa. 

time. 


caller. 

getc,  getchar,  fgetc. 

vadviae  - 

abutdown  -  close  down  the  ayatem  at  a 

and  time  to  ASCII,  ctime,  localtime, 
fiab  -  play  “ 
aetjmp,  longjmp  -  non-local 


graph  -  draw  a 

gprof  -  diaplay  call 
perfmon  - 

gxteat  -  stand  alone  teat  for  the  Snn  video 
colordemot  -  demonstrate  Sun  Color 
draw  -  interactive 
plot  - 
eg  -  Snn  color 

are,  move,  cent,  point,  linemod,  apace,  doaepi  - 

plot  - 

vgiind  - 
cbgrp  -  change 
getpgrp  -  get  process 
killpg  -  send  signal  to  a  process 
aetpgrp  -  set  process 

getgroups  - 
initgronpa  -  initialise 
aetgronps  -  set 
group  - 

getgigid,  getgmam,  actgrent,  endgrent  -  get 


getgmam,  setgrent.  endgrent  -  get  group  file . 

getgroups  -  get  group  access  list . . . 

gethoatbyaddr,  getbostbyname,  setbostent, 
getbostbyname,  setbostent,  endhostent  -  get 

getbostent,  gethoatbyaddr,  getbostbyname . 

getbostid  -  get  unique  identifier  of  current  host . 

get  hostname,  setb  oat  name  -  get /set  name  of  current  <  « 

getitimer,  setitimer  -  get/set  value  of  interval  . 

getlog  -  get  user's  login  name.  .  .  . . 

getlogin  -  get  login  name . .  •  •  . 

getnetbyaddr,  get  net  byname,  setnetent,  endnetent  -  «  • 

getnet byname,  setnetent,  endnetent  -  get  network  .  *  . 
getnetent,  getnetbyaddr,  getnet  byname,  setnetent,  .  •  • 

getopt,  optarg,  optind  -  get  option  letter  from . 

getpagesise  -  get  system  page  sise . 

getpaas  -  read  a  password . 

getpeemame  -  get  name  of  connected  peer.  . 

getpgrp  get  process  group . .  .  .  •  « 

getpid  *  get  process  id . 

getpid,  getppid  -  get  process  identification . 

getppid  -  get  process  identification . 

getpriority,  setpriority  -  get/set  program  . 

get  protobyname,  setprotoent,  endprotoent  -  get  •  *  •  . 
getprotobynnmber,  getprotobyname,  setprotoent,  «  *  • 
getprotoent,  getprotobynnmber,  getprotob3mame,  •  •  • 

getpw  -  get  name  from  uid . .  » 

getpwent,  getpwuid,  getpwnam,  setpwent,  endpwent  - 
getpwnam,  setpwent,  endpwent  -  get  password  file  «  •  « 
getpwuid,  getpwnam,  setpwent,  endpwent  -  get  •  .  •  « 

gctrlimit,  setrliznit  -  control  maximum  system . 

getrusage  -  get  information  about  resource  . 

gets,  fgets  >  get  a  string  from  a  stream . 

getaervbyname,  setservent,  endaervent  -  get  . 

getservbypoit,  getservbyname,  setservent, 

getservent,  getservbypoit,  getaervbyname . .  , 

getsockname  -  get  socket  name . 

geisockopt,  setaockopt  -  get  and  set  options  on  «  •  •  , 
gettable  -  get  NIC  format  host  tables  from  a  host  •  •  • 

gettimeofday,  settimeofday  -  get/sei  date  and  . 

getty  -  set  terminal  mode.  .  •  * . 

gettytab  ~  terminal  configuration  data  base . 

geiuid,  geteuid  -  get  user  identity.  •  *  ♦  . . 

getuid,  getgid  -  get  user  or  group  ID  of  the  . 

getw  *  get  character  or  integer  from  stream . 

getwd  -  get  current  working  directory  pathname.  •  •  • 

give  advice  to  paging  system . 

given  time . . . 

glob;  filename  expand  argument  list . 

gmtime,  asetime,  timesone,  dysiie-  convert  date  .  •  • 
Go  Fish'* . . 

goto . . 

goto:  command  transfer . 

gprof  -  display  call  graph  profile  data . 

g»I>k . 

graph  -  draw  a  graph . 

graph  profile  data.  .  «  * . 

graphical  display  of  general  system  statistics . 

graphics  board . * . 

Qrapbica  Diaplay . * . . 

graphics  drawing . . . 

gnphics  filten . .  , 

graphics  interface.  . 

graphics  interface,  /erase,  label,  line,  circle,  . 

graphics  interface . . . 

grep,  egrep,  fgrep  -  search  a  file  for  a  patten.  «  .  •  .  . 

grind  nice  listings  of  programs.  . .  *  .  *  , 

group . 

group . .  *  .  . 

group . 

group . . . . . 

group  -  group  file . . . . 

group  access  list . . . .  «  • 

group  access  list . . . . . 

group  access  list . . . . 

group  file . .  «  . . .  , 

group  file  entry,  getgrent, . 


getgrent(3) 

getgroups(2) 

gctbostent(3N) 

getb08tent(3N) 

getbo8tent(3N) 

gethosttd(2) 

getbo8tname(2) 

getitimei(2) 

gctIog(3P) 

getIogin(3) 

getnetent(3N) 

getnetent(3Nj 

getnetent(3N) 

getopt(3C) 

get  pages  ise(2) 

getpas8(3) 

getpeername(2) 

g«tpBrp(2) 

getpidlSF) 

getpidf2) 

getpid(2) 

getpriority(2) 

getprotoentl3Nl 

getpiotoent(3N) 

getprotoent(3N) 

getpw(3) 

geCpwent(3l 

getpwent  (3) 

getpwent(3) 

gctiliinit(2) 

getniaag^2) 

get8(3S) 


getserventfSN) 

get8ervent(3N) 

gct8ervent(3N) 

getaockname(2) 

getsockopt(2) 

gettable(8C) 

gettimeofday(2) 

gctty(8) 

gettytab(5) 

gctuid(2) 

getuid(3F) 

gctc(3S) 

getwd(3) 

vadvise(2) 

Bbtttdown(8) 

csb(l} 

etime^S) 

fi8k(6) 

setjmp(3) 

€8b(l) 

gprof(l) 

grapb(lG) 

graph(lG) 

gprof(l) 

peifmon(l) 

gxte8t(8s) 

colordemos(6) 

draw  (6) 

plot(lG) 

cb(4S) 

plot(3X) 

plot(S) 

8rep(l) 

vgrind(l) 

cbgTp(l) 

getpgrp(2) 

killpg(2) 

8etpgrp(2) 

group(6) 

getgroap8(2) 

initgroups(3) 

8etgToup8(2) 

gioup(6) 

getgTent(3) 
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sctregid  -  set  re&t  and  effective  ^roap  ID . .  8etregid(2) 

ectmidi  eetgid,  setegid,  setrgid  -  set  user  and  group  fD.  aetaid,  seteuid, . .  8etaid(3) 

getttid,  getgid  -  get  nser  or  group  ID  of  the  caller . getuid(3F) 

getegid  -  get  group  identity . getgid(2) 

group#  show  group  memberships . groups(l) 

chowa,  fchown  -  change  owner  and  group  of  a  file . chown(2) 

make  -  maintain  program  groups . . . make(l) 

groups  -  show  group  memberships . group3(l) 

worm  -  Play  the  growing  worm  game . .  worm(6) 

stty,  gtty  -  set  and  get  terminal  state . 8tty(3C) 

graphics  board,  gxtest  -  stand  alone  test  for  the  Sun  video  . gxte8t(S8) 

halt  -  stop  the  processor.  . ha]t(8) 

stop:  halt  a  job  or  process . C8h(l) 

reboot  -  reboot  system  or  halt  processor . reboot(2) 

fastboot)  fasthalt  -  reboot/  halt  the  system  without  checking  the  disks . fast  boot  (8) 

nnail  -  handle  remote  mail  received  via  uucp . nnail(8) 

re^comp,  rejexec  -  regular  expression  handler. . regex(3) 

hangman  -  Computer  version  of  the  game  hangman . hangmaii(6) 

hangman  -  Computer  version  of  the  game  hangman.  •  «  hangman(6) 

vhangup  -  virtually  “  hangup^'  the  current  control  terminal . vhangup(2) 

nohup:  run  command  immune  to  hangups . csh(l) 

crash  -  what  happens  when  the  system  crashes . cra8h(8s) 

link  -  make  a  hard  link  to  a  file.  . Iiiik(2) 

intro  -  introduction  to  special  files  and  hardware  support . intro(4) 

uptime  -  show  how  long  system  has  been  up . . . *  .  uptime(l) 

checknews  -  check  if  user  has  news  on  the  USENET  news  network . checknews(l) 

rehash:  recompute  command  hash  table . csh(l) 

unhash:  discard  command  hash  table.  . . cshfl) 

hashstat:  print  command  bashing  statistics . cahfl) 

hashstat:  print  comnund  hashing  statistics . .  •  csh(l) 

leave  ~  remind  you  when  you  have  to  leave . Ieave(l] 

help  -  ask  for  help . he[p(l) 

help  -  ask  for  help . belp(l) 

od  -  octal,  decimal,  hex,  ascii  dump.  . od(l) 

bier  -  file  system  hierarchy.  . . hier(7) 

hier  file  system  hierarchy . hier(7) 

history:  print  history  event  list . . . C8h(l) 

history:  print  history  event  list . csh(l) 

fortune  -  print  a  random,  hopefully  interesting,  adage . .  .  fortuue(6) 

gethoitid  -  get  unique  identifier  of  current  host . gttho8tid(2) 

gethostname,  sethostname  -  get/set  name  of  current  host . getho8tuame(2) 

hostnm  -  get  name  of  current  host . . . .  hostnm(3F) 

rdate  -  set  system  date  from  a  remote  host . rdate(8) 

uusend  -  send  a  file  to  a  remote  host . uu8eiid(lC) 

gettable  -  get  NIC  format  host  tables  from  a  host . . . gettable(8C) 

htoni,  ntohl,  ntohs  -  convert  values  between  host  and  network  byte  order,  htonl,  . byteorder(3N) 

remote  -  remote  host  description  file.  . remote(5) 

sethostent,  endhostent  -  get  network  host  entry,  /gethostbyaddr,  gethost byname . getho8tent(3N) 

hosts  -  host  name  data  base . . . bo8t8(5) 

phones  -  remote  host  phone  number  data  base . phones(5) 

ruptime  «  show  host  status  of  local  machines . ruptime(lC) 

hostid  -  print  identifier  of  current  host  system . ho8tid(l) 

hostname  -  set  or  print  name  of  current  host  system.  .  . . ho8tname(l) 

htable  *  convert  NIC  standard  format  host  tables . htable(8) 

gettable  -  get  NIC  format  host  tables  from  a  host . gettable(8C) 

hostid  -  print  identifier  of  current  host  system . hostid(l) 

system,  hostname  -  set  or  print  name  of  current  host  . hostname(l] 

hostnm  -  get  name  of  current  host . ho8tiim(3F) 

hosts  -  host  name  data  base.  *  . . ho8ta(5) 

uptime  -  show  how  bug  system  has  been  up . uptime(l) 

htable  -  convert  NIC  standard  format  host  tables.  .  •  .  htable(8) 

between  host  and  network  byte  order,  htonl,  htons,  ntohl,  ntohs  -  convert  values . byteorder(3N) 

and  network  byte  order,  htonl,  htons,  ntohl,  ntohs  -  convert  values  between  host  •  •  .  byteorder(3N) 

wump  -  the  game  of  hunt-the-wumpus . . . wump(6) 

sinh,  cosh,  tanh  -  hyperbolic  functions . .  •  .  .  .  sinh(3M) 

hypot,  cabs  -  Eudidean  distance.  •  . . .  ,  hypot(3M) 

getarg,  iaxgc  -  return  command  line  arguments.  getarg(3F) 

icheck  -  file  system  storage  consistency  check . iclieck(8) 

icmp  -  Internet  Control  Message  Protocol . icmp(4P) 

getpid  *  get  process  id . . . getpid(3F) 

setregid  -  set  real  and  effective  group  ID.  . . setregid(2) 

setgid,  setegid,  setrgid  -  set  user  and  group  ID.  setuid,  seteuid,  setmid,  . setaid(3) 

getuid,  getgid  -  get  user  or  group  ID  of  the  caller.  . «...  getuid(3F) 

su  -  substitute  user  id  temporarily.  «  .  . . su(l) 

form,  idate,  itime  -  return  date  or  time  in  numerical . idate(3F) 

getpid,  getppid  -  get  process  identification.  ,  . . getpid(2) 
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gethostid  -  get  unique 
boetid  -  print 
whnt- 

getgid,  getegid  -  get  gronp 
getuid,  getenid  -  get  naer 
letrenid  -  aet  reaJ  and  effective  naer 
pezTor,  gerror, 


checknewa  -  check 
exit,  export,  login,  newgrp,  rend,/  ib,  for,  cnie, 

inierfnee.  vp  - 
abort  -  terminate  abruptly  with  memory 
core  -  format  of  memory 
gcore  -  get  core 

notify:  reqneat 
nobnp:  mn  command 
xatr  -  extract  atringv  from  C  program*  to 
eyacc  -  modified  yacc  allowing  mneb 
ar  -  Arebive  1/4 
im  -  tapemaater  i/2 
which  -  locate  a  program  file 
dump,  dnmpdatea  - 
dump  - 
reitore  - 

indent  - 

tgetfiag,  tgetstr,  tgoto,  tpnta  -  terminal 
iainf,  ianan  -  teat  for 
ptx  -  permuted 

itmeat,  tt^emp,  atmemp,  atrepy,  atmepy,  atrlen, 

objeett. 

refereacea  in  a/  indxbib  -  make  inverted 

laat-> 
ayacall  - 

faplit  -  aplit  a  multi-routine  Fortran  file  into 
.br  look  bib  -  find  reference!  in  a  bibliograpjiy. 

aervera  - 

ineijaetof,  inet^ntoa  -  Internet  addresa/ 

addreaa/  inet.addr,  inet_network,  inet^akeaddr, 
Internet  addreaa/  inetjiddr,  iuet jietwork, 
inetjaddr,  inet.network,  inet^makeaddr,  inetjnaof, 
Inetjuetof,  inetjatoa  -  Internet/  inei.addr, 
/inetjnakeaddr,  inetjnaof,  inetjaetof, 

dumpfa  -  dump  file  ayatem 
pac  printer/ plotter  accounting 
getruaage  ~  get 
vtimea  -  get 
fatab  -  atatic 

man  -  print  out  manual  pagei;  find  manual 

newarc  - 

miicellaneoua  -  miacetlaneoua  uiefol 


init  -  proceaa  control 
ioinit  -  change  f77  I/O 
ttya  -  terminal 
initgroupi  - 
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popen,  pcloae  * 

generator,  routinea  for  changing/  random,  arandom, 
flmin,  flmax,  dflmia,  dfimax, 
clri  -  dear 
fa. 

read,  readv  -  read 
aoelim  -  eliminate  .ao'a  from  nroff 
acanf,  facanf,  aacanf  -  formatted 
ungetc  -  puab  character  back  into 
fread,  fwrite  -  buffered  binary 
atdio  -  atandard  buffered 
feiTor,  feof,  clearerr,  fileno  -  atream  statua 
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identify  the  veraion  of  filea . . . 

identity.  . . . 

identity.  . .  •  * 
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iermo  -  get  ayatem  error  meaaagea . 
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inquiries . . 


getho8tid(2) 

ho8iid(l) 

what(l) 

ffetpd(2| 

getuid(2) 

8etreuid(2) 

penoifSP) 

lf(4N) 

c*h(l) 

checknews(l) 

•h(l) 

ifconfig(8C) 

vp(4S) 

abort(dF) 

core(5) 

gcore(l) 

imemtest(88) 

cshfl) 

C8h(l) 

xst^l) 

eyacc(l) 

ai(4S) 

tm(4S) 

whichil) 

dumpisj 

dump(8) 

reftore(8) 

indentfl) 

indent{l] 

iermcap(3X) 

isinf(8) 

ptx(l) 

8tring($) 

index(3F) 

indxbib(l) 

ia8t(l) 

sy8call(2) 

ffplit(l) 

indxbi^l) 


ierven(5) 

inet(3N) 

inetd(8C) 

inet(SN) 

inet(3N) 

inct(SN) 

inet(3N) 

inet(3N) 

inews(l) 

dumpf8(8) 

p*c(8) 

Betni».ge(2) 

vtimes(3C) 

f8tab(5) 

man(l) 

newsr^fi) 

intro(7) 

init(8] 

initgFoups(3) 

init(8) 

ioinit($F) 

tty8(6) 

initgroups(3) 

connect(2) 

popen(3S) 

random(3) 

range(3P} 

clri(8) 

f.(5\ 

read(2) 

8oelim(l] 

8canf(3S) 

nngetc(3$) 

fread(3S) 

intro(3S) 

feiTO]^3S) 


January  1984 


-  XX  • 


Sun  System  Release  1.1 


Permuted  Indent 


refer  -  find  and  insert  literature  references  in  docnments . refer(l) 

insqne*  remqne  -  insert /remove  element  from  a  qneae . inaque(3) 

qnene.  insqne,  remqne  ^  insert/remove  element  from  a  •  •  .  •  insque(3) 

install  -  install  nies . insta]I(l) 

install  -  install  files . tnstall(l) 

draw  -  interactive  graphics  drawing . draw(6) 

fsck  -  file  system  consistency  check  and  interactive  repair . fsck(8) 

fortune  -  print  a  random,  hopefully  interesting,  adage . fortune(6) 

eg  -  Sun  color  graphics  interface . cg(4S) 

ec  -  SCom  10  Mb/s  Ethernet  interface . ec(4S) 

ell  -  Sun  $  Mb/s  experimental  Ethernet  interface . . . en(4S) 

lo  -  software  loopback  network  interface . lo(4) 

mti  -  SjTstech  MTI*800/1600  multi-terminal  interface.  •  *  . . .  ,  mti(4S) 

mtio  -  UNIX  magnetic  tape  interface . mtio(4) 

coni,  point,  linemod,  space,  closepl  -  graphics  interface,  /erase,  label,  tine,  circle,  arc,  move,  . ptot(3X) 

plot  -  graphics  interface . plot(5) 

tty  -  general  terminal  interface . tty(4) 

-  Ikon  1007 1-5  Multibus  Vcrsatec  parallel  printer  interface,  vp  . .  .  «  vp(4S) 

Versatec  printer/plotter  and  Centronics  printer  interface,  vpc  -  Systech  VP02200  . vpc(4S) 

ifeonfig  -  configure  network  interface  parameters . ifconfig(8C) 

telnet  -  user  interface  to  the  TELNET  protocol . .  tcliiet(lC) 

if  -  general  properties  of  network  interfaces . .  if(4N) 

Bwapon  -  add  a  swap  device  for  interleaved  paging/swapping . swapo]i(2) 

sendmail  -  send  mail  over  the  internet . sendmail(8) 

inet.makeaddr,  inet Jnaof,  inet^etof,  inei^ntoa  -  Internet  address  manipulation.  /inei_nctwork . inct(3N) 

iemp  -  Internet  Control  Message  Protocol . icmp(4P) 

ftpd  -  DARPA  Internet  File  Transfer  Protocol  server . ftpd(8C) 

ip  -  Internet  Protocol . ip(4P) 

inet  -  Internet  protocol  family . inet(4F) 

inetd  -  internet  services  daemon . inetd(8C) 

tep  -  Internet  Transmission  Control  Protocol . tcp(4P) 

ndp  -  Internet  User  Datagram  Protocol . udp(4P) 

ip  -  Disk  driver  for  Interphase  2180  SMD  Disk  Controller . ip(4S) 

spline  -  interpolate  smooth  curve . spline(lG) 

pti  -  phototypesetter  interpreter  . pti(l) 

px  -  Pascal  interpreter  . px(l) 

pix  -  Pascal  interpreter  and  executor . pix(l) 

pt  -  Pascal  interpreter  code  translator . pi(l) 

esh  -  a  shell  (command  interpreter)  with  C-like  syntax . c8h(l) 

pipe  -  create  an  interprocess  communication  channel . pipe(2) 

-  atomically  release  blocked  signals  and  wait  for  interrupt,  sigpause . 8igpau8e(2) 

onintr  process  interrupts  in  command  scripts . .  «  .  .  .  C8h(l) 

sleep  -  suspend  execution  for  an  interval.  * . sleepll) 

steep  -  suspend  execution  for  interval . «...  sleep(3) 

steep  -  suspend  execution  for  an  interval  . . 8!eep(3F) 

intro  -  introduction  to  commands.  .  ,  . . jntro(l) 

intro  -  introduction  to  compatibility  library  functions . intro(3C) 

intro  -  introduction  to  FORTRAN  library  functions . iiitro(3F) 

intro  -  introduction  to  library  functions . .  iiitro(3) 

intro  -  introduction  to  mathematical  library  functions . intro(3M) 

intro  -  introduction  to  network  library  functions . intro(3N) 

intro  -  introduction  to  other  libraries . intro(3X) 

intro  -  introduction  to  special  files  and  hardware  support.  «  «  «  intro(4) 

intro  -  introduction  to  system  calls  and  error  numbers.  ,  *  •  •  intro(2) 

commands,  intro  -  introduction  to  system  maintenance  and  operation  «  .  «  iniro(8) 

ncheck  -  generate  names  from  i-nnmbers.  «  «  «  . . ncheck(8) 

find  references  in  a  bibliography,  indxbib  -  make  inverted  index  to  a  bibliography  .br  lookbib  -  . indxbib(l) 

tread,  twrite,  trewin,  tskipf,  tstate  -  f77  tape  I/O.  topen,  tclose . topen(3F) 

ioinit  -  change  f77  I/O  initialiiation . .  ioinit(3F) 

select  -  synchronons  I/O  multiplexing . setect(2) 

mem,  kmem,  mbmem,  mbio  -  main  memory  and  I/O  space . . . mem(4S) 

iostat  -  report  I/O  statistics . .  iostat(8) 

popen,  pclose  -  initiate  I/O  to/from  a  process . popen(3S) 

iocti  -  control  device . .  ,  .  ioctl(2) 

ioinit  -  change  f77  I/O  initialiiation.  »«...••«.  ioinit(3F) 

iostat  -  report  I/O  statistics . *  . . iostat(8) 

Controller,  ip  -  Disk  driver  for  Interphase  2180  SMD  Disk . ip(4S) 

ip  -  Internet  Protocol.  .  •  . . ip(4P) 

sail  -  multl-nser  wooden  ships  and  iron  men . 8aii(6) 

whatis  -  describe  what  a  command  is.  . . . . whatia(l) 

isalpha,  isupper,  islower,  isdigit,  isxdigit,  iaalnum,  tsspace,  ispnnet,  isprint,  iscntrl,/  . ctype(3) 

isalnum,  isspace,  ispnnet,  isprint,  iscntrl,/  isalpha,  isupper,  islower,  isdigit,  isxdigit . ctype(3) 

/isainnm,  isspace,  ispnnet,  isprint,  iscntrl,  isascii,  isgraph,  toupper,  tolower,  toascii  -/  . ctype(3) 

ttynam,  isatty  -  find  name  of  a  terminal  port . ttynam(3F) 

ttyname,  isatty,  ityslot  -  find  name  of  a  terminal . ttyname(3) 

/isxdigit,  isalnum,  isspace,  ispnnet,  isprint,  iscntrl,  isascii,  isgraph,  toupper,  tolower,/  . ctype(3) 
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is  print,  iscntrl,/  isalphn,  isnpper,  islower, 
/isspnce,  ispnnct,  isphnt,  iscntrl,  isnscii, 
point  vnines. 

ispunct,  isprint,  iscnti!,/  is&lphn,  isupper, 
vxlaes.  isinf, 

/isdigit,  isxdigit,  isalnumt  issp&ce,  ispnnct, 
/islower,  isdigit,  isoc  digit,  isaJnnm,  isspnce, 
/isnpper,  islower,  isdigit,  isxdigit,  isatnum, 

system  - 

isspace,  ispnnct,  isprint,  iscntrl,/  isalplia, 
iscntrl, /  isalpha,  isupper,  islower,  isdigit, 
vi  -  view  a  file  witliont  changing 
idatt, 

rpow  -  multiple  precision  integer  arithmetic 
suspend:  suspend  a  shell,  resuming 

jO, 

jo.  jl. 

bg:  place 
fg:  bring 
jobs:  print  current 
stop:  halt  a 

crontab  -  table  of  times  to  run  periodic 

kill:  kill 
Iprm  -  remove 


default  table, 
makekey  -  generate  encryption 
table,  kbd  - 

print  out  manual  pages;  find  manual  information  by 

profile  bufen. 

process. 

kill: 

chase  -  Try  to  escape  to 
mem, 

<|uii  -  test  your 

linemod,  space,  ctosepl  -  graphics/  openpl,  erase, 
awk  -  pattern  scanning  and  processing 
be  -  arbitrary-precision  arithmetic 
set,  shift,  times,  trap,  umask,  wait  -  command 

epp  -  the  C 
order 

frdcp, 

leave  -  remind  you  when  you  have  to 

exit: 

index,  rindex,  Inbink, 
ftruucate  *  truncate  a  file  to  a  specified 
getopt,  optaig,  optind  -  get  option 

lex  -  generator  of 
intro  -  introduction  to  other 
rantib  -  convert  archives  to  random 
torder  -  find  ordering  relation  for  an  object 
ar  -  archive  ( 
intro  *  Introduction  to 
intro  -  introduction  to  compatibility 
intro  -  introduction  to  FORTRAN 
intro  -  introduction  to  mathematical 
intro  -  introduction  to  network 
ar  -  archive  and 
esh  -  a  shell  (command  interpreter)  with  C- 

limit:  alter  per-process  resonree 
unlimii;  remove  resource 
ulimit  -  get  and  set  user 
getarg,  large  ^  return  command 
space,  closepi  -  graphics/  openpl,  erase,  label, 

bk- 
Ipr  -  off 


isdtgii,  isxdigit,  isalnum,  isspace,  ispunci,  . 

isgrapb,  toupper,  tolower,  toascii  -  character/  *  ♦  - 
isinf,  isnan  -  test  for  indHerminate  floating  *  .  •  • 

istower,  isdigit,  isxdigit,  isalnum,  isspace,  . 

isnan  -  test  for  indeterminate  floating  point  »  •  *  • 

isprint,  iscntrl,  isascii,  is^aph,  tonpper,/  . 

ispunci,  isprint,  iscntrl,  isascii,  isgrapb,/  ,  •  •  •  . 

isspace,  ispunci,  isprint,  iscntrl,  isascii,/ . 

issue  a  shell  command.  •  /  /  ; . 

isupper,  islower,  isdigit,  isxdigit,  isalnum,  . 

isxdigit,  isalnum,  isspace,  ispun^,  isprint . 

it  using  the  vi  visual  editor.  *  *  . 

itime  -  return  date  or  time  in  numerical  form.  •  •  • 
itom,  madd,  msub,  mult,  mdiv,  min,  mout,  pow,  ged, 

its  superior.  . . . . 

jO,  jl,  jn,  yO,  yl,  yn  -  bcsscl  functions. 

jl.  jn,  yO,  yl,  yn  -  bessel  functions . 

jn,  yO,  yl,  yn  -  bessel  functions . 

job  in  background . . . 

job  into  foreground . 

job  list.  . . . 

job  or  process.  •  •  * . 

jobs . . . 

jobs  and  processes . * 

jobs  from  the  line  printer  spooling  queue.  «  •  •  *  • 

jobs:  print  current  job  list . .  • 

join  -  relational  database  operator.  . 

kbd  -  keyboard  translation  table  format  and  .  •  • 

key . .  ♦  • 

keyboard  translation  table  format  and  default  •  •  • 

keywords,  man  -  . * . 

kgmon  -  generate  a  dump  of  the  operating  system’s 

kill  -  send  a  signal  to  a  process . 

kill  -  send  a  signal  to  a  process,  or  terminate  a  •  •  * 

kill  -  send  signal  to  a  process . 

kill  jobs  and  processes . . . 

kill:  kill  jobs  and  processes . .  *  «  * 

kilter  robots.  . . 

killpg  -  send  signal  to  a  process  group . 

kmem,  mbmem,  mbio  -  main  memory  and  I/O  space. 

knowledge . *  '  . 

label,  line,  circle,  arc,  move,  cent,  point, 

language . . . 

language . 

language,  /export,  login,  newgrp,  read,  readonly, 

language  preprocessor.  . . . 

lastcomm  -  show  last  commands  exeented  in  reverse 

Id  -  link  editor.  . . 

Idexp,  modf  -  split  into  mantissa  and  exponent.  •  , 

leave.  . . * . 

leave  -  remind  you  when  you  have  to  leave . 

leave  shell.  . . 

ten  -  tell  about  character  objects . 

length,  truncate, . .  . . 

letter  from  aigv . . . . 

lex  -  generator  of  lexical  analysis  programs . 

lexical  analysis  programs.  •  . . 

libraries.  ♦  .  •  . . .  * 

libraries . . . 

library . 

library)  file  format . 

library  functions . 

library  functions . . . 

library  functions . . . 

library  functions . 

library  functions . . . 

library  maintainer.  . * 

tike  syntax . . 

limit:  alter  per-process  resource  limitaitons . 

limitations . . 

limitiations.  * . . 

limits . 

line  arguments.  . * . 

line,  circle,  arc,  move,  cont,  point,  linemod . 

line  discipline  for  machine-machine  communication.  • 
line  print . . 
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Ipe  -  line  printer  control  program . lpc(8) 

lp<!  -  tine  printer  daemon . lpd(8) 

Iprm  -  lemore  job9  from  the  line  printer  spooling  qnene . )prm(l) 

/eraDe»  tabel,  line,  circle,  arc,  move,  cent,  point,  linemod,  space,  closcpt  -  graphics  interface . plot(3X) 

comm  -  select  or  reject  lines  common  to  two  sorted  files . comm(l) 

fold  -  fold  long  lines  for  finite  width  onipnt  device.  .  . . fold(l) 

nniq  -  report  repeated  lines  in  a  file . . . . uniq(l) 

look  -  find  lines  in  a  sorted  list . . . took(l) 

rev  -  reverse  lines  of  a  file . . . 

head  -  display  first  few  lines  of  specified  files . head(l) 

readtlnk  -  rea^  value  of  a  symbolic  link . readlink(2) 

link  '  make  a  hard  link  to  a  file.  . . . Iink(2) 

Id  -  link  editor.  »  »  . . Id(l) 

i.ont  -  assembler  and  link  editor  output . a.oiit(5) 

link,  symink  -  make  a  link  to  an  existing  file . link(3F) 

link  -  make  a  hard  link  to  a  file . tink(2) 

eymlink  -  make  symbolic  link  to  a  file . * . 8ymlink(2) 

link,  symink  -  make  a  link  to  an  existing  file . . . link(3F) 

In  -  make  links . ln(l) 

lint  -  a  C  program  verifier . linl(l) 

glob:  filename  expand  argument  list . . . C8h(l) 

history:  print  history  event  list.  . . C8h(l) 

jobs:  print  cnirent  job  list.  * . c8h(l) 

shift:  manipulate  argument  list . . . .  »  .  C8h(l) 

getgroups  -  get  group  access  list.  *  . . getgroups(2) 

initgronps  -  initialise  group  access  list . . . initgroup8(3) 

look  -  find  lines  in  a  sorted  list . look(l) 

niist  get  entries  from  name  list . * . nli8t(3) 

nm  -  print  name  list . nm(l) 

setgronps  -  set  group  access  list . 8etgroups(2) 

varargs  -  variable  argument  list.  . . varargs(3) 

Is  -  list  contents  of  directory.  * . i8(l) 

foreach:  loop  over  list  of  names . .  C8h(l) 

nsen  -  compact  list  of  users  who  are  on  the  system . n8er8(l) 

listen  -  listen  for  connections  on  a  socket . )isten(2) 

listen  -  listen  for  connections  on  a  socket . )i8teQ(2) 

vgrind  -  grind  nice  listings  of  programs . .  ,  .  vgrind(l) 

refer  -  find  and  insert  literature  references  in  documents . referfl) 

In  -  make  links . In(l) 

index,  rindex,  Inblnk,  ten  -  tell  about  character  objects . .  •  •  index(3F) 

lo  -  software  loopback  network  interface . !o(4) 

loc  -  return  the  address  of  an  object . loc(3F) 

convert  date  and  time  to  ASCII,  ctime,  localtime,  gmtime,  asetime,  timexone,  dysize  -  . ctime(3) 

(esh  only),  which  -  locate  a  program  file  including  aliases  and  paths  ...  *  which(l) 

whereis-  locate  source,  binary,  and/or  manual  for  program.  .  •  .  wherei3(i) 

end,  et ext,  edata-  last  locations  in  program . end(3) 

flock  -  apply  or  remove  an  advisory  lock  on  an  open  file . flock(2) 

*1og^n’^  lockscreen  -  maintain  window  context  until  . lock8creen(l) 

-  collect  system  diagnostic  messages  to  form  error  log.  dmesg  . . dme8g(8) 

syslog,  openleg,  closelog  control  system  log . *  . . syslo^a) 

syslog  -  make  system  log  entry . syslo^l) 

gamma  -  log  gamma  function . gamma(3M) 

power,  square  root,  exp,  log,  loglO,  pow,  sqrt  -  exponential,  logarithm,  . exp(3M) 

syslog  -  log  systems  messages . syslogfS) 

square  root,  exp,  log,  loglO,  pow,  sqxt  -  exponential,  logarithm,  power,  ....  exp(3M) 

exp,  log,  loglO,  pow,  sqrt  -  expenenti^,  logarithm,  power,  square  root . exp(3M) 

rwho  '  who*8  logged  in  on  local  machines . rwho(lC) 

flush  -  flush  output  to  a  logical  unit . fin8h(3F) 

fseek,  ftell  **  reposition  a  file  on  a  logical  unit . f8eek(3F) 

getc,  fgetc  -  get  a  character  from  a  logical  unit.  .  . . getc(3F) 

putc,  fputc  -  write  a  character  to  a  FORTRAN  logical  unit . putc(3F) 

lockscreen  ^  maintain  window  context  until  **  login" . lock8cieezi(l) 

rtogitt  -  remote  login . . . rlogin(lO) 

login  -  sign  on.  . logiD(l) 

ac  -  login  accounting . a(^8) 

login:  login  new  user . cah(l) 

getlog  -  get  user^s  login  name . getlog(3F) 

getlogin  -  get  login  name.  .  . . get!ogiD(3) 

login:  login  new  user. . C8h(l) 

/.,  break,  continue,  cd,  eval^  exec,  exit,  export,  login,  newgrp,  read,  readonly,  set,  shift,  times,/  . h(l) 

passwd  -*  change  login  password . pas8wd(l) 

utmp,  wtmp  -  login  records . utmp(5) 

' '  riogind  -  remote  login  server.  . r1ogind(8C] 

chsb  -  change  default  login  shell . chsh(l) 

last  -  indicate  last  logins  of  naers  and  teletypes . .  last(l) 

bsuncube  -  view  3-D  Sun  logo . b3uncobe(6) 
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logotti:  end  session . 

seijmp,  lonsjmp  -  non^locil  goto.  . . 

look  -  find  lines  in  %  sorted  list . 

/-  inverted  index  to  n  bibtiopnphj  .br  lookbib  -  Snd  reference*  in  n  bibliosnpbj.  . 

break:  exit  wbile/foreach  loop . . . 

continue:  cycle  in  loop,  .  . . 

end:  terminate  loop . . . . 

foreach:  loop  over  list  of  names.  . . 

lo- software  loopback  network  interface . . . 

library,  lorder  -  find  ordering  relation  for  an  object  . 

I  pc  -  line  printer  control  program . 

Ipd  -  line  printer  daemon.  . . . 

Ipq  -  spool  queue  examination  program . 

Ipr  -  off  line  print . . . 

queue.  Ipim  -  remove  jobs  from  the  line  printer  spooling  •  «  • 

is  -  list  contents  of  directory.  . 

Iseek,  tell  -  move  read/write  pointer.  . 

stat,  Istat,  fstat  -  get  file  status . 

m4  -  macro  processor.  . 

sun  -  is  current  macbine  a  sun  workstation . 

vax  •  is  current  macbine  a  vax.  . . 

bk  -  line  discipline  for  machine*  macbine  communication.  . . 

bk  '  line  discipline  for  machine-machine  communication . 

ruptime  *  show  host  status  of  local  machines . 

rwho  >  who^B  logged  in  on  local  machines . 

m4  -  macro  processor.  . . 

alias:  shell  macros.  . . 

toascii  -  character  classification  and  conversion  macros,  /isascii,  isgraph,  tonpper,  tolower^  . 

ms  -  text  formatting  macros . . 

me  -  macros  for  formatting  papen . * 

man  -  macros  to  t3rpe8et  manual . 

-  multiple  precision  integer  arithmetic,  itom,  madd*  msub,  mult,  mdiv,  min,  mout,  pow,  gcd,  rpow  •  • 

tp  -DEX7/  mag  tape  formats.  . . . 

mtio-UNlX  magnetic  tape  interface.  ♦  . . *  • 

mt  -  magnetic  tape  manipnlating  program . 

rmt  -  remote  magtape  protocol  modnie . * . . 

mail  -  send  and  receive  mail . 

pimail  -  print  out  waiting  mail . . .  .  .  . 

recnews  -  receive  unprocessed  articles  via  mail.  . . . . 

recnews  -  receive  unprocessed  articles  via  mail . . 

sendnews  -  send  news  articles  via  mail . •  •  . . . 

-  encode/decode  a  binary  file  for  transmission  via  mail,  unencode, uudecode  . 

uuree receive  processed  newt  articles  via  'mail.  .  . . . . 

xsend,  xget,  enroll  -  secret  mail.  •  •  .  .  .  •  •  *  \  . . 

mail  -  send  and  receive  mail. 

/bln/  mail  -  send  dr  receive  mail  among  users . 

mailaddr-  mail  addressing  description.  . . 

biff-  mail  alarm.  . . . 

newatiases  -  rebuild  the  data  base  for  the  mail  aliases  file.  . . . . . 

/bin/mail  -  send  or  receive  mail  among  . . 

from  -  who  is  my  mail  froint . . . 

sendmail  -  send  mail  over  the  internet.  . . 

imail  -  handle  remote  mail  received  via  tiucp.  . . . 

mailaddr  -  mair  addressing  description . 

inem,  kmem,  mbmem,  mbio  -  main  memory  and  I/O  space.  . . . 

make-  maintain  program  groups.  . . . 

lockscrten  -  maintain  window  context  until  “login”. 

ar  -  archive  and  library  maintainer.  . 

intro  -  introduction  to  system  maintenance  and  operation  cbnunands . 

make  -  maintain  program  groups.  . 

delta  -  make  a  delta  (change)  to  an  SCCS  file.  . 

mkdir  -  make  a  directory.  . 

mkdir-  make  a  directory  file.  . . 

link  -  make  a  hard  link  to  a  file . 

link,  symlnk  -  make  a  link  to  an  existing  file.  . 

mknod  -  make  a  special  file . 

mktemp  -  make  a  nnique  file  name.  . . . 

-  find  references  in  a  bibliography,  indxbib  -  make  inverted  index  to  a  bibliography  .br  lookbib  «  .  , 

In  -  make  links . . . 

symlink  -  make  symbolic  link  to  a  file . 

systog  -  make  system  log  entry . 

MAKEDEV  -  make  system  special  files . 
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man  -  macros  to  typeset  manual . man(7) 

information  by  keywords,  man  -  print  out  manual  pages;  find  manual  . man(l) 

shift:  manipulate  argument  list . C8h(l) 

quota  -  manipulate  disk  quotas . quota(2) 

route  -  manually  manipulate  the  routing  tables . route(8C) 

mt  -  magnetic  tape  manipulating  program . . mt(l) 

inet.neiof,  inetjitoa  -  Internet  address  manipulation,  /inet.makeaddr,  Inetjnaof,  . inet(3N) 

frexp,  Idexp,  modf  -  split  into  mantissa  and  exponent . . . frexp(3) 

catman  *  create  the  cat  files  for  the  manual . catman(8) 

man  -  macros  to  typeset  manual . man(7) 

whereis  -  locate  source,  binary,  and/or  manual  for  program . whcrei3(l) 

man  -  print  out  manual  pages;  find  manual  information  by  keywords . .  ,  •  ,  *  man(l) 

man  -  print  out  manual  pages;  find  manual  information  by  keywords.  ,  .  man(l) 

route  -  manually  manipulate  the  routing  tables . rout^SC) 

tee  copy  standard  output  to  many  files . tee(l) 

umtsk:  change  or  display  file  creation  mask . C8h(l) 

sigsetmask  -  set  current  signal  mask.  «  .  •  . . . . aig8etmask(2) 

umask  -  set  file  creation  mode  mask . . . umask(2) 

mkstr  *  create  an  error  message  file  by  massaging  C  source . .  •  .  •  •  mksiifl) 

intro  -  introduction  to  mathematical  library  functions . intro(3M) 

eqn,  neqn,  checkeq  -  typeset  mathematics . «q&(l) 

getrlimii,  setriimit  -  control  maximum  system  resource  consumption . getriimit(2) 

▼limit  -  control  maximum  system  resource  consumption . vlimit(3C) 

mb  -  Multibus . mb(4S) 

mem,  kmem,  mbmem,  mbio  -  main  memory  and  I/O  space . mem(4S) 

mem,  kmem,  mbmem,  mbio  -  main  memory  and  I/O  space . mem(4S) 


en  -  Sun  9  Mb/s  experimental  Ethernet  interface . en(4S) 

as  -  mcfiSOOO  assembler .  . “(0 

precwioB  iiktegcr/  itom,  nutdd,  msab,  malt,  mdiv,  mm,  moat,  pow,  ecd,  rpow  -  maltiple . mp(3X) 

me  -  macros  for  formatting  papers . me(7) 

bed  -  conTeit  to  antique  media . bcd(6) 

space,  mem,  kmem,  mbmem,  mbio  -  main  memory  and  I/O  .  .  mem(4S) 

groups  -  show  group  membenhips.  . . . . group8(l) 

mmap  -  map  pages  of  memory.  *  •  . . mmap(2) 

munmap  -  unmap  pages  of  memory.  <•  «  . . munmap(2) 

malloe,  free,  realtoc,  calloe,  efree,  alloca  -  memory  allocator.  . . . mal1oc(3) 

▼alloc  -  aligned  memory  allocator.  . vaIloc(3) 

mem,  kmem,  mbmem,  mbio  -  main  memory  and  I/O  space . mem(4S) 

▼fork  -  spawn  new  process  in  a  ▼irtual  memory  efficient  way . . . ▼fork(2) 

abort  -  terminate  abruptly  with  memory  image . abort(3F) 

core  -  format  of  memory  image  file . corc(5) 

▼msUt  -  report  virtual  memory  statistics.  . ▼mstat(8) 

imemtest  -  stand  alone  memory  test . .  .  imeinte8t(88) 

sail  -  multi-user  wooden  ships  and  iron  men . . . 8ai!(6) 

sort  -  sort  or  merge  files.  . . 8ort(l) 

pmerge  -  pascal  file  merger.  . pmerge(l) 

mesg permit  or  deny  messages . me8g(l) 

mkstr  -  create  an  error  message  file  by  massaging  C  source . mksttfl) 

reev,  rccvfrom.  recvmsg  -  receive  a  message  from  a  socket . rccv(2) 

send,  sendto,  sendmsg  -  send  a  message  from  a  socket . end(2) 

temp  ^  Internet  Control  Message  Protocol.  . icmp(4P) 

error  -  analyse  and  disperse  compiler  error  messages . . . error(l) 

mesg  >  permit  or  deny  messages.  »  .  .  . meag(l] 

B3rB^eiTliBi,  sys^neir,  erino  -  system  error  messages,  perror,  . perror{3) 

peiTor,  ^iTor,  iermo  -  get  system  error  messages . .  ,  ,  perror(3F) 

psignal,  sys^eiglist  -  system  signal  messages . p8ignal(3) 

syslog  -  log  systems  .  messages . yslog(8) 

dmesg  -  collect  system  diagnostic  messages  to  form  error  tog.  * . dme8g(8) 

mille  -  play  Mille  Bomes . mil]e(6) 

milk  -  play  Milk  Domes . milk(6) 

integer  arithmetic.  Itom,  madd,  msub,  mult,  mdiv,  min,  mout,  pow,  ged,  rpow  ^  multiple  precision  ,  «  «  ,  mp(3X) 

pages,  miscellaneous  -  miscellaneous  useful  information  «  .  .  «  intro(7) 

miscellaneous  -  miscellaneous  useful  information  pages . intro(7) 

mkdir  -  make  a  directory . mkdiifl ) 

mkdir  -  make  a  directory  file.  •  *  •  . . mkdiif2) 

mkfs  -  construct  a  file  system . mkf8(8) 

mknod  -  build  special  file . mknod(8) 

mknod  -  make  a  special  file . . . mknod(2) 

mkproto  -  construct  a  prototype  file  system . mkproto(8) 

C  source,  mkstr  -  create  an  error  message  file  by  massaging  .  ,  .  mkstifl) 

mktemp  -  make  a  unique  file  name . mktemp(3) 

mmap  -  map  pages  of  memory . mmap(2) 

chmod- change  mode . chmod(l) 

getty  -  set  terminal  mode.  .  «  .  . . getty(8) 

umask  -  set  file  creation  mode  mask.  *  .  .  a . uinask(2) 
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chmod  -  change 
chmod,  fchmod  -  change 
frexp^  Idexp, 
touch  -  update  date  tart 
rccoveiy,  eyacc  - 
rmt  -  remote  magtape  protocol 
monitor,  moortartup, 
execution  profile, 
bdemos  demonstrate  Sun 

monop  - 
profile,  monitor, 

cunes  -  screen  functions  with  ^^optimal”  cursor 
col  -  filter  reverse  paper 
mount,  amount 
mount,  umount  - 


mtab  ^ 
mouse  -  Sun 

arithmetic,  itom,  madd,  msub,  mult,  mdiv,  min^ 
graphics/  open  pi,  erase,  label,  line,  circle,  arcr 

mv- 
Iseek,  tell  - 

multiple  precision  integer  arithmetic,  itom,  madd, 


interface, 
mti  -  Systech 

eyacc  -  modified  yacc  allowing 
precision  integer  arithmetic,  itom,  madd,  msub, 

mb  - 

yp  -  Ikon  10071-6 
pr  -  print  file(8),  possibly  in 
msub,  mult,  mdiv,  min,  mout,  pow,  gcd,  rpow  - 
select  -  synchronous  I/O 
fsptit  -  split  a 
mti  -  Systech  MTI-800/1600 
sail  - 
switch: 


from  -  who  is 
getenv  -  value  for  environment 
getlog  -  get  user’s  login 
getlogin  -  get  login 
getsockname  -  get  socket 
mktemp  -  make  a  unique  file 
pwd  -  print  working  directory 
tty  -  get  terminrt 
hosts  -  host 
networks  -  network 
protocols  -  protocol 
services  -  senrice 
tmpnam  -  create  a 
getpw  •  get 
nlirt  -  get  entries  from 
nm  -  print 
rename  -  change  the 
ttyname,  isatty,  ttjrslot  -  find 
ttynam,  isatty  -  find 
getpeemame  -  get 
gethostname,  sethortname  -  get/set 
hortnm  ^  get 
hostname  -  set  or  print 
bind  '  bind  a 
foreach:  loop  over  list  of 
ftcheck  -  generate 


eqn. 


mode  of  a  file.  . . 

mode  of  file.  . . 

modf  -  split  into  mantissa  and  exponent.  ♦  «  • 

modified  of  a  file . . 

modified  yacc  allowing  much  improved  error  .  » 

module.  . . . . . 

monconirol  -  prepare  execution  profile.  «... 
monitor,  monstartup,  moncontrol  -  prepare  .  • 

Monochrome  Bitmap  Display . 

monop  -  Monopoly  game.  . . 

Monopoly  game . .  •  •  *  ^ 

monrtariup,  moncontrol  -  prepare  execution  .  . 
more,  page  -  browse  through  a  text  file.  .... 

motion . 

motions.  .  . . 

mount  and  dismount  file  sjrstem . .  » 

mount  or  remove  file  system. 

mount,  umount  mount  and  dismount  file  system. 

mount,  umount  mount  or  remove  file  ssrstem. 

mounted  file  system  table . 

mouse . 

mouse  -  Sun  mouse. 

mout,  pow,  gcd,  rpow  multiple  precision  integer 
move,  cont,  point,  linemod,  space,  closepl  -  .  . 

move  or  rename  files . . 

move  read/write  pointer.  . 

ms  -  text  formatting  macros . 

msub,  mult,  mdiv,  min,  mout,  pow,  gcd,  rpow  - 
mt  *  magnetic  tape  manipulating  program.  .  . 

mtab  -  mounted  file  system  table . 

mti  -  Systech  MTI-800/1600  multi-teiminil  .  . 
MTI-800/1600  multi-terminal  interface.  .... 

mtio  -  UNIX  magnetic  tape  interface . 

much  improved  error  recovery. . 

mult,  mdiv  min,  mout,  pow,  gcd,  rpow  -  multiple 

Multibus . . . 

Multibus  Versatec  parallel  printer  interface.  •  . 

multiple  columns . . . 

multiple  precision  integer  arithmetic,  itom,  madd, 

multiplexing.  . . . 

multi-routine  Fortran  file  into  individual  files. 

mnltt-terminal  interface.  . . 

multi-user  wooden  ships  and  iron  men . 

multi-way  command  branch . . 

munmap  -  unmap  pages  of  memory.  . 

mv  -  move  or  rename  files . 

my  mail  from? . 

name. . 

name . 

name . *  «  •  • 

name . *  .  *  •  . 

name.  . . 

name.  . . 

name . .  .  . . 

name  data  base.  . . 

name  data  base.  . . 

name  data  base.  . 

name  data  base.  . *  • 

name  for  a  temporary  file. . . 

name  from  uid . 

name  list . 

name  list . 

name  of  a  file . . 

name  of  a  terminal . 

name  of  a  terminil  port . 

name  of  connected  peer . 

name  of  current  host . 

name  of  current  host.  . . . 

name  of  current  host  system . 

name  to  a  socket . 

names . . 

names  from  i-numbers . * 

Dcheck  -  generate  names  from  i-numbers.  •  .  * 

nd  -  network  disk  control.  •  . . 

nd  -  network  disk  driver  . . 

neqn,  checkeq  -  typeset  mathematics . 


.  .  .  chmod(SF) 

.  .  .  chmod(2) 

•  .  .  frexp(3) 

.  .  .  touch(l) 

.  .  ♦  eyacc(l) 

.  .  .  rmt(8C) 

.  •  .  monitorfs) 

«  .  .  monitoT^S) 

.  .  .  bdemos(6) 

.  .  .  monop(6) 

•  •  •  monop(6) 

•  •  •  monitor(3) 

.  .  •  more(l) 

.  .  .  curBes(3X) 

•  .  •  col(i) 

.  »  .  inount(8) 

.  .  •  mount(2) 

.  .  .  mountfS) 

.  .  ,  mount(2) 

.  .  «  mtab(6) 

.  .  .  mouse(4S) 

.  •  .  mou8e(4S) 

...  mp(3X) 

.  .  .  plot(3X) 

.  *  .  mv(l) 

.  .  .  l8eek(2) 

.  .  .  m8(7) 

.  .  .  mp(3X) 

.  .  .  mt(l) 

»  .  •  mtal^5) 

.  «  .  mtif4S) 

...  mti(4S) 

«  .  «  mtio(4) 

.  .  .  e]rMc(l) 

.  .  .  inp(3X) 

.  .  .  mb(4S) 

.  .  .  vp(4S) 

•  •  •  Pt(l) 

.  .  .  mp(3X) 

.  ,  .  select(2) 

...  f8plit(l) 

.  .  .  mti(4S) 

.  .  .  sailfG) 

•  .  .  C8h(l) 

...  munmai>(2) 

•  •  .  mv(l) 

.  .  .  from(l) 

.  .  .  getenv(3) 

.  .  .  getlog(3P) 

.  .  *  getlogin(3) 
...  get80ckname(2) 
.  •  •  mktemp(3) 

•  ♦  ♦  p»<*(0 
.  .  .  ttjr(l) 

.  .  .  bosts(5) 

.  .  .  aetworks(6) 
...  protoco!8(5) 
...  8ervtce8(S) 

«  •  «  tmpnam(3C) 

.  .  .  getpw(3) 

,  .  .  nlirt(s) 

.  .  «  nm(l) 

•  .  .  rename(2) 

.  .  .  ttyname(3) 

•  •  .  ttynam(3F) 

.  •  •  getpeemame(2) 
.  .  .  gethostname(2) 
.  .  .  hortnm(3F) 
...  hortname(l) 

«  .  .  bind(2) 

.  .  .  C8h(l) 

•  .  «  ncheck(8) 

...  ncheck(8) 

.  .  .  nd(8C) 

.  .  .  nd(4P) 

.  .  .  eqn(l) 
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netstat  -  show  network  status . iiet5tat(8) 

-  check  if  user  has  news  on  the  US^£T  news  network,  checknews  . check  iiew8(l) 

ntohlf  ntohs  -  convert  values  between  host  and  network  byte  order,  htoni,  htons . byteorder(3N) 

nd  -  network  disk  control . nd(8C) 

nd  -  network  disk  driver.  . . . nd(4P) 

getnetbsmame,  setneteni,  endnetent  -  ^t  network  entry,  getnetent,  getnetbyaddr,  ««.••••  getnetent(3N) 
gethostbyname,  sethostent,  endhostent  -  get  network  host  entry,  gethostent,  gethostbyaddr,  .  .  ♦  .  gethosteiit(3N) 

lo  -  software  loopback  network  interface . . . lo(4) 

ifeonfig  -  configure  network  interface  parameters . ifconfig(8C) 

if  -  general  properties  of  network  interfaces . . . if(4N) 

intro  -  introduction  to  network  library  functions . intro(3N) 

networks  -  network  name  data  base . .  .  .  .  .  network8(5) 

news  -  USENET  network  news  article,  utility  files . new8(5) 

routing  -  system  supporting  for  local  network  packet  routing . routin^4N) 

routed  -  network  routing  daemon . routed(8C) 

netstat  show  network  status . netstat(8) 

networks  -  network  name  data  base . networks(3) 

creat  -  create  a  new  file . . . creat(2) 

-  open  a  file  for  reading  or  writing,  or  create  a  new  file,  open  . .  open(2) 

newfs  -  construct  a  new  file  system . newf8(8) 

fork  -  create  a  new  process . .  fork(2) 

vfork  -  spawn  new  process  in  a  virtual  memory  efficient  way.  *  «  •  «  «  vfork(2) 

login:  login  new  user.  . . C8h(l) 

ad duser  -  procedure  for  adding  new  users . .  «  •  addusei{8) 

aliases  file,  newaliases  -  rebuild  the  data  base  for  the  mail . newalia8e8(8) 

newfs  -  construct  a  new  file  system . ncwfs(8) 

/continue,  cd,  eval,  exec,  exit,  export,  login,  newgrp,  read,  readonly,  set,  shift,  times,  trap,/ . h(l) 

news  -  USfilNET  network  news  article,  utility  files.  «  .  «  news(5) 

news  -  USENET  network  news  article,  utility  files . news(5) 

expire  -  remove  outdated  news  articles . expire(8) 

inews  -  submit  news  articles . inew8(l) 

postnews  -  submit  news  articles . postnewsfl) 

xeadnews  -  read  news  articles . readnews(l) 

sendnews  -  send  news  articles  via  mail . 8endnew8(8) 

uurec  -  receive  processed  news  articles  via  mail . .  uurec(8) 

checknews  -  check  if  user  has  news  on  the  USENET  news  network . . . .  checkuews(l) 

checknews  -  check  if  user  has  news  on  the  USENET  news  network . checknews(!) 

checkBew8(l).  newsrc  -  information  file  for  readnews(l)  and  . newarc(5) 

dbminit,  fetch,  store,  delete,  firstkey,  nextkey  -  data  base  subroutines . .  dbm(3X) 

gettable  -  get  NIC  format  host  tables  from  a  host . gfttabIe(8C) 

htable  -  convert  NIC  standard  format  host  tables . htable(8) 

nice  -  set  program  priority . nice(3C) 

ygrind  -  grind  nice  listings  of  programs . vgnnd(l) 

only),  nice,  nohup  -  run  a  command  at  low  priority  (sh  •  .  •  .  nice(l) 

nice:  run  low  priority  process . C9h(l) 

nlist  -  get  entries  from  name  list . nlist(3) 

nm  -  print  name  list . nm(l) 

ctri  -  clear  i-  node.  . . clri(8) 

nice,  nohnp  -  run  a  command  at  low  priority  (sh  only).  .  .  «  nice(l) 

nohup:  run  command  immune  to  hangups . csh(l) 

setjmp,  longjmp  -  non-local  goto . 8etjmp(3) 

notify:  request  immediate  notification . C8h(l) 

notify:  request  immediate  notification . C8h(l) 

relationships  of  screens,  adjacentscreens  -  notify  tho  window  driver  of  the  physical . adiaceiit8creen8(l) 

term  -  terminal  driving  tables  for  nroff.  . term(5) 

term  -  terminal  driving  tables  tot  nroff.  .  ,  .  . tenii(5) 

nroff  -  text  formatting  and  typesetting . nroff(l) 

soelim  -  eliminate  .8o*s  from  nroff  input . 8oelim(l) 

tbi  - format  tables  for  nroff  or  troff.  . . . . tbl(l) 

cotert  -  filter  nroff  output  for  CRT  previewing . colcrt(l) 

deroff  *  remove  nroff,  troff,  tbi  and  eqn  constructs.  *  »  •  . . deroff(l) 

checknr  -  check  nroff/troff  files . . . checknii^l) 

network  byte  order,  htoni,  htons,  ntohl,  ntohs  -  convert  values  between  host  and  •  •  «  »  byteorder(3N) 

byte  order,  htoni,  htons,  ntohl,  ntohs  -  convert  values  between  host  and  network  •  .  .  byteorder(3N) 

null  -  data  sink.  .  «  •  . . null(4} 

fptype  -  check  a  floating  point  number . * . fptyp^3F) 

-  get  the  file  descriptor  of  an  external  unit  number,  getfd . getfd(3F) 

number  -  convert  Arabic  numerals  to  English . numberf6) 

phones  '  remote  host  phone  number  data  base.  . .  phones(5) 

arithmetic  ^  provide  drill  in  number  facts . arithmettc(6) 

rand,  srand  -  random  number  generator.  •  . . . . rand(3C) 

/srandom,  initstate,  setstate  -  better  random  number  generator;  routines  for  changing  generators.  ,  .  raudoza(3) 

atof,  atoi,  ato]  -  convert  ASCII  to  numbers . .  •  •  »  . . atof(3) 

intro  -  introduction  to  system  calls  and  error  numbers . tiitro(2) 

ncheck  -  generate  names  from  i-  numbers.  •  «  . ncheck(8) 

number  -  convert  Arabic  numerals  to  English . *  .  »  »  number(6) 
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idatc,  itime  -  return  date  or  time  tn 
twrite,  tiewin»  tekipf,  trtate  -  177  tape  1/ 
toe  -  return  the  addreea  of  an 
aiie  '  eise  of  an 
lorder  -  0nd  ordering  relation  for  an 
strings  -  find  printable  strings  in  an 
index,  rindex,  Inblnk.  ten  -  tell  about  character 

od  - 

oct  -  Central  Data 

acet  -  turn  accounting  on  or 
login  -  sign 

nice,  ttohnp  -  run  a  command  at  low  priority  (sh 
a  program  file  including  aliases  and  paths  (esh 
create  a  new  file, 
file,  open  - 
fopeUj  freopen,  fdopen  - 
flock  *  apply  or  remove  an  advisory  lock  on  an 
closedir  directory  operations. 

syslog, 

cont,  point,  linemod,  space,  closepl  -  graphics/ 
savecore  -  save  a  core  dump  of  the 
kgmon  -  generate  a  dump  of  the 
intro  -  introduction  to  system  maintenance  and 
tgetstr,  tgoto,  tputs  -  terminal  independent 
bcopy,  bemp,  biero,  ffs  -  bit  and  byte  string 
ietldir,  seekdir,  rewinddir,  closedir  -  directory 
dkio  -  generic  disk  control 
strepy,  stmepy,  strten,  index,  j^dex  -  string 
join  -  relanohal  database 
getopt, 

curses  -  screen  functions  with  “ 
getopt,  optaig, 
getopt,  optaig,  optind  -  get 
fenti  -  file  control 
stty  -  set  terminal 
getsockopt,  setsockopt  -  get  and  set 

-  convert  values  between  host  and  network  byte 
iastcomm  -  show  last  commands  executed  in  reverse 

lorder  -  find 
vi  -  screen 
cpio  -  copy  file  archives  in  and 
expire  -  remove 
a.out  -  assembler  and  link  editor 

-  terminate  a  process  after  flushing  any  pending 

'  fread,  fwrite  -  buffered  binary  input/ 
ecvt,  fevt,  gevt  - 
printf,  fprintf,  sprintf  -  formatted 
fold  -  fold  long  lines  for  finite  width 
eolcit  -  fitter  aroff 
stdio  -  standard  buffered  input/ 
flush  -  flush 
tee  -  copy  standard 
foreach:  loop 
sendmail  send  mail 
exec: 

chown  -  change 
chown,  fchown  -  change 
quot  -  summarise  file  system 

diag  -  General-purpose  stand-alone  utility 
stdio  standard  buffered  input/output 
routing  -  system  supporting  for  local  network 

more, 

getpagesiie  -  get  system 
pages!  se  -  print  system 
miscellaneous  -  miscellaneous  useful  information 
man  -  print  out  manual 
mmap  -  map 
munmap  -  unmap 

swapon  -  specify  additional  device  for 
drum  - 

vadvise  -  give  advice  to 


numerical  form . 

O.  topen,  tclose,  tread, . . . . 

object.  .  •  . . 

object  file . 

object  library . . . . . 

object,  or  other  binary,  file,  . . . 

objects.  . . . . . 

oct  -  Central  Data  octal  serial  card . .  • 

octal,  decimal,  hex,  ascii  dump . 

octal  serial  card . . . . 

od  -  octal,  decimal,  hex,  ascii  dump . .  •  • 

off.  . 

on . * . . 

onintr:  process  interrupts  in  comnund  scripts . 

. 

enly).  which  -  locate  . . . . 

open  -  open  a  file  for  reading  or  writing,  or  . . 

open  a  file  for  reading  or  writing,  or  create  a  new  «  ♦  «  * 

open  a  stream.  . . 

open  file . -  . . 

opendir,  readdir,  telldir,  seekdir,  rewinddir,  . 

openiog,  closelog  -  control  system  tog . 

openpl,  erase,  label,  line,  circle,  arc,  move,  «  . . 

eperating  system . 

operating  S3r8tem’s  profile  buffers . 

operation  commands . 

operation  routines,  tgetent,  tgetnum,  tgetflag, . 

operations . *  «  • 

operations,  opendir,  readdir,  . . 

operations . 

operations,  streat,  stmeat,  stremp,  stmemp,  . 

operator . 

optaig,  optind  -  get  option  letter  from  aigv. . 

optimal”  cursor  motion . 

optind  -  get  option  letter  from  argv.  . 

option  letter  from  argv . 

options . 

options . . . 

options  on  sockets . .  .  «  »  . 

order,  htonl,  htons,  ntohl,  ntohs . 

Older. . 

ordering  relation  for  an  object  library . 

oriented  (visual)  display  editor  based  on  ex . 

out . * . 

outdated  news  articles . 

ontput.  . . 

output,  exit . 

output . 

output  conversion . . . 

ontpnt  conversion.  . . * . 

output  device.  . . . . 

output  for  CRT  previewing . 

ontpnt  package . 

output  to  a  logical  unit . 

output  to  many  files.  . . 

over  list  of  names . . . . 

over  the  internet.  . . 

overlay  shell  with  specified  command . 

owner.  •  «  *  . . 

owner  and  group  of  a  file . . . 

ownenhip . 

pac  -  printer/plotter  accounting  infonnation . 

package . 

package.  «  «  «  . 

packet  routing.  . 

page  -  browse  through  a  text  file . 

page  site.  . . 

page  site . . 

paffcs . 

pages;  find  manual  infonnation  by  keywords . 

pages  of  memory . 

pages  of  memory . 

pagesise  -  print  system  page  site.  ,  . . 

paging  and  swapping . 

paging  device . 

paging  system.  . . 


idate(3P) 

topenfSF) 

loc(3P) 

sife(l) 

lordeitl) 

string^!) 

tndex(3P) 

oct(4S) 

od(l) 

oct(4S) 

od(l) 

acct(2) 

login(l) 

C8h(l) 

nic^l) 

which(l) 

open(2) 

open(2) 

fopen(3S) 

flock(2) 

directoiy(3) 

sy8log(3) 

plot(3X) 

8avecorc(8) 

kgmon(8) 

intro(8) 

teimcap(3X) 

b8tring(3) 

directory(3) 

dkio(4S) 

8tring(3) 

join(l) 

getopt(3C) 

cur8e8(3X) 

getoptr3C) 

getopt(3C) 

fCDtl(5) 

8tty(l) 

get80ckopt(2) 

byteorder(3N) 

lastcomm(l) 

loideifl) 

vi(l) 

cpio(l) 

expirc(8) 

a.out(5) 

exit(3) 

fread(3S) 

ecvt(3) 

printf(3S) 

fold(l) 

cotcrt(l) 

intro(3S) 

flQ8h(dF) 

tce(l) 

€8h(l) 

sendmail(8) 

C8h(l) 

chown(8) 

chown(2) 

qnot(8) 

p»(<8) 

diag(8s) 

intro(3S) 

roating(4N) 

more(l) 

getpagc8ise(2) 

pagesise(l) 

intro(7) 

man(l) 

mmap(2) 

munma^2) 

pagesiieCl) 

8wapon(8) 

dmm(4) 

vadvi8e(2) 
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ffw&poa  -  add  a  swap  device  for  interteaved 
aocketpair  -  create  a 
col  -  filter  reverae 
me  -  macroa  for  formattini^ 
vp  -  Ikon  10071-fi  MnltlbuB  Veraatec 
ifeonfig  -  confif  are  network  interface 

pc- 
pxref  “ 
pxp- 
pmerge  - 
px  - 
pix  - 

pi- 


getpaaa  -  read  a 
paeawd  -  change  login 
paaawd  - 
vipw  -  edit  the 

getpwuid,  getpwnam,  aetpwent,  endpwent  -  get 
getwd  -  get  cnirent  working  directory 
getewd  -  get 

-  locate  a  program  file  including  aliaaea  and 
grep,  egrep,  fgrep  aearch  a  file  ^r  a 


popen, 

getpeemame  -  get  name  of  connected 
exit » tenninate  a  proceaa  alter  fluahing  any 

atatiaticB. 

crontab  -  table  of  timea  to  ran 
meag  - 
ptx  " 
limit:  alter 
meaaagea. 
error  meaaagea. 
sticky  -  executable  files  with 
phones  -  remote  host 


pti  - 

adjacentacreeni  -  notify  the  window  driver  of  the 

split  -  split  a  file  into 
channel. 

bg: 
fiah- 
mille  - 
boggle  <- 
worm  - 


pac  -  printer/ 

vpc  -  Syatech  VPC-2200  Veraatec  printer/ 

trpfpoi  fpeent  -  trap  and  repair  floating 
erase,  label,  line,  circle,  arc,  move,  cont, 
fptype  -  check  a  floating 
iainf,  ianan  -  teat  for  indeterminate  floating 
laeek,  tell  -  move  read/write 
popd: 


ttynam,  iaatty  *  find  name  of  a  terminal 
ttytype  -  data  base  of  terminal  types  by 
pr  -  print  file(8), 
analyse  ~  Virtual  Ubhx 

itom,  madd,  maub,  mult,  mdiv,  min,  moat, 
root,  exp,  log,  loglO, 
log,  logic,  pow,  sqrt  -  exponential,  logarithm, 

be  -  arbitrary- 

mult,  mdiv,  min,  moot,  pow,  ged,  rpow  -  multiple 
monitor,  monatartup,  moncontrol  - 


paging/ffwapping . 

pair  of  connected  socket  a . 

paper  motiona . 

papera . 

parallel  printer  interface.  «  «  ,  «  . . 

parameters.  .  •  . . 

Pascal  compiler . 

Pascal  cross-reference  program . 

Pascal  execution  profiler.  . . 

pascal  file  merger.  . 

Pascal  interpreter.  . 

Pascal  interpreter  and  executor . 

Pascal  interpreter  code  translator . 

paaawd  -  change  login  password . 

paaawd  -  password  file . 

password.  «  .  . . 

password . 

password  file.  * . 

password  file . 

password  file  entry,  getpwent . 

pathname . 

pathname  of  current  working  directory . 

paths  (esh  only),  which . 

pattern.  .  ♦  .  . . 

pattern  scanning  and  processing  language.  .  »  . 

pause  -*  stop  until  signal . .  • 

pc  -  Pascal  compiler . 

petose  initiate  I/O  to/from  a  process . 

peer.  . 

pending  output.  . . 

peifmon  -  graphical  display  of  general  system 

periodic  jobs . 

permit  or  deny  messages . 

permuted  index . 

per-process  resonree  limitations . .  ,  * 

perror,  gerror,  iermo  -  get  system  error  .  .  *  • 
perror,  sysjerilist,  sysjiieir,  eimo  -  system  •  . 

persistent  text . 

phone  number  data  base . 

phones  -  remote  host  phone  number  data  base. 

phototypesetter  interpreter.  . 

physic^  relationships  of  screens . 

pi  -  Pascal  interpreter  code  translator . 

pieces . . . 

pipe  -  create  in  interproccaa  communication  •  « 

ptx  -  Pascal  interpreter  and  executor . 

place  job  in  background . 

play  “Go  Fish’’ . 

play  Mille  Bomes . 

play  the  game  of  boggle . 

Play  the  growing  worm  game . 

plot  ~  graphics  filters . 

plot  -  graphics  interface.  . 

plotter  accounting  information . .  ,  . 

plotter  and  Centronics  printer  interface.  .  •  .  . 

pmerge  -  pascal  file  merger.  . 

point  faults.  «  . . 

point,  linemod,  space,  ctosepl  ^  graphics/  open  pi, 

point  number . 

point  values . .  .  . 

pointer . . . 

pop  shell  directory  stack . 

popd:  pop  shell  directory  stack . 

popen,  pclose  -  initiate  I/O  to/from  a  process.  » 

port . .  4  .  •  4  ,  • 

port.  .  . . 

possibly  in  multiple  columns . 

postmortem  crash  analyier.  . 

postnews  -  submit  news  articles . . 

pow,  ged,  rpow  -  multiple  precision  integer/  »  » 
pow,  sqrt  -  exponential,  logarithm,  power,  square 

power,  square  root,  exp . 

pr  -  print  file(a),  possibly  in  multiple  columns. 

precision  arithmetic  language . 

predsiou  integer  arithmetic,  itom,  madd,  msub, 
prepare  execution  profile . 


awapon(2) 

80cketpaii(2) 

col(l) 

me(7) 

vp(4S) 

ifconfig(8C) 

pc(l) 

pxref(l) 

pxp(l) 

pinerge(l) 

px(l) 

pix(l) 

Pi(l) 

pa8awd(l) 

pa8swd(S) 

gctpa58(3) 

pa8swd(l) 

passwd(5) 

vipw(8) 

gctpwent(3) 

getwd{3) 

gctcwd(3F) 

which(l) 

grep(l) 

awk(l) 

pau8e(3C) 

pc(l) 

popen(3S) 

getpeername(2) 

cxit(3) 

perfmon(l) 

crontab(5) 

mcsg(l) 

ptx(l) 

C8h(l) 

peiTor(3F) 

pcrroi(3) 

8ticky(8) 

phones(5) 

phoDe8(5) 

pti(l) 

adj  aceiit8creen8(  i ) 

Pi(l) 

split(l) 

pipe(2) 

pix(l) 

cah(l) 

fi8h(6) 

mille(6) 

boggle(6) 

worm(6) 

plot(lG) 

p!ot(5) 

pa.c(8) 

vpc(4S) 

pmcrge(l) 

trpfpe(3F) 

pIot(3X) 

fptype(3F) 

i8inf(3) 

t8eek(2) 

C8h(l) 

C8h(l) 

popen(dS) 

ttynam(3F) 

ttytypc(5) 

Pr(l) 

analyfe(8) 

po5tnews(l) 

mp(3X) 

cxp(3M) 

exp(3M) 

Pr<l) 

bc(l) 

mp(3X) 

mouitor(3) 


Sun  System  Release  1.1 


•  xxix  • 


January  1984 


Permuted  I  tides 


cpp  -  the  C 

colcit  -  filter  nroff  output  for  CRT 
anget  -  undo  u 
typei- 
Ipr  -  off  line 
fortune  - 
pn- 
kuhstni: 
jobi: 
rnct  - 


pr- 
fpr- 
hifftoiy: 
hoitid  - 
banner  * 


nm  - 

hoftnnme  set  or 
keywords,  mu  - 
printeiiT  - 
pimnil  - 
pstxt  - 
ptfesige- 

pwd  - 
file,  strings  -  find 


buner  -  print  large  banner  on 
printcap  - 
Ipc  “  line 
Ipd  -  line 

vp  -  Ikon  1007 1>5  Multibus  Versatec  parallel 
VPC-2200  Versatec  printer/ plotter  and  Centronics 
Ipnn  -  remore  jobs  from  the  line 
pac  - 

▼pc  -  Systech  VPC-2200  Versatec 
conTCTsion. 

setpriority  *  get/sei  program  scheduling 
nice  -  set  program 
renice  -  alter 
nice:  ruh  tow 
nice,  nohup  -  run  a  commud  at  low 

adduser  - 

reboot  -  UNIX  bootstrapping 
nice:  run  low  priority 
stop:  halt  a  job  or 
^exit  -  terminate  a 
fork  -  create  a  new 
fork  -  create  a  copy  of  this 
kill  -  send  a  signal  to  a  process,  or  terminate  a 
kill  -  send  signal  to  a 
kill  -  send  a  signal  to  a 
popen,  pciose  -  initiate  I/O  to/from  a 
wait  -  await  completion  of 
exit  -  terminate  a 
init  - 
getpgrp  -  get 
killpg  -  send  signal  to  a 
setpgp-set 
getpid  -  get 
getpid,  getppid  *  get 
vfork  -  spawn  new 
onintr 

kill  -  send  a  signal  to  a 
limit:  alter  per* 
ps- 
times  -  get 
wait  -  wait  for  a 
wait,  waits  -  wait  for 
ptrace  - 
exit  -  terminate 
uurcc  -  receive 
kill:  kill  jobs  and 
gcore  -  get  core  images  of  running 
renice  -  alter  priority  of  running 
wait:  wait  for  background 


preprocessor.  . . 

previewing . 

previous  get  of  u  SCCS  file.  •  .  . . 

primitive  system  data  types.  .  . . 

print . 

print  a  random,  hopefully  interesting,  adage.  .  •  •  •  • 

print  an  SCCS  file.  . . . 

print  commud  hashing  statistics . 

print  current  job  list . 

print  current  SCCS  file  editing  activity . .  •  • 

print  file(8),  possibly  in  multiple  columns . 

print  Fortran  file . 

print  history  event  list . 

print  identifier  of  current  host  system.  . 

print  large  buner  on  printer.  . 

print  name  list . 

print  name  of  current  host  system.  •  «  •  * . 

print  out  muual  pages;  find  manual  information  by 

print  out  the  environment . 

print  out  waiting  mail . 

print  system  facts.  . 

print  ssrstem  page  site.  . 

print  working  directory  name.  •  •  •  . . 

printable  strings  in  u  object,  or  other  binary . 

printcap  -  printer  capability  data  base.  . 

printenv  -  print  ont  the  environment.  ••«*♦*«* 

printer.  . . 

printer  capability  data  base. 

printer  control  program . 

printer  daemon. 

printer  interface . . . 

printer  interface,  vpc  -  Systech  . 

printer  spooling  quene.  •  •  .  «  . . 

printer/plotter  accounting  information . 

printer/plotter  and  Centronics  printer  interface.  .  .  . 

printf,  fprintf,  sprintf  -  formatted  output . 

priority,  getpriority . .  •  .  • 

prioritjr . 

priority  of  running  processes . 

priority  process . 

priority  (sh  only) . 

prmail  -  print  out  waiting  mail . 

procedure  for  adding  new  users . 

procedures . . . 

procesp . 

procesi . . . 

procet*.  ♦  .  •  . . . . . 

process . 

process . . . 

process . 

process . * . 

process . . . 

process.  . . . 

process . 

process  after  Hushing  any  pending  output . 

process  control  initialisation . 

process  group.  «  . . 

process  group . 

process  ^np . 

process  id.  .  •  «  •  .  .  . . 

process  identificatsom . 

process  in  a  virtual  memory  efficient  way . 

process  interrupts  in  commud  scripts . 

process,  or  teminate  a  process . .  •  ♦  • 

process  resource  limitations.  . . 

process  status. 

process  times . .  »  «  • 

process  to  terminate . 

process  to  terminate  or  stop . . 

process  trace . .  . . . 

process  with  status. 

processed  news  articles  via  mail . .  « 

processes.  . . . 

processes . 

processes,  . . 

processes  to  complete . 


ep|)(l) 

colcrtfll 

ungei(l) 

type8(S) 

Ml) 

fortnneffi) 

prB(l) 

csh(l) 

C8h(l) 

2® 

ho8tid(l) 

banners) 

nm(l) 

hostname(l) 

mu(l) 

printeny(l) 

prmail(l) 

P8tat(8) 

pagesise(l) 

pwd(l) 

strings(l) 

printcap(S) 

printenv(l) 

banner(6) 

printcap(5) 

M8) 

lpd(8) 

vp(4S) 

'vpe(4S) 

Ipnn(l) 

P*e(8) 

vpc(4S) 

printf(3S) 

getpriority(2) 

nice(3C) 

renice(8) 

csh(l) 

nic^l) 

prmail(l) 

adduseifS) 

rebooi(8) 

cshfl) 

cMi) 

exit(2) 

fork(2) 

fork(3P) 

kill(l) 

kill2) 

kill(3P) 

popen(3S) 

wait(l) 

exit(3) 

init(8) 

getpgrp(2) 

kiUpg(2) 

•etpgrp(2) 

getpid(3F) 

getpid(2) 

vfork(2) 

esk(l) 

kill(l) 

csh(l) 

P8(l) 

times(3C) 

wait(3F) 

wait(2) 

ptrace(2) 

cxit(3F| 

uurec(8) 

C8h(l) 

gcore{l) 

renice(8) 

C8h(l) 
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&wk  -  pattern  ocanamg  and 
halt  -  stop  the 
m4  -  macro 
reboot  -  reboot  eyetem  or  halt 


monetartop,  moncontiol  -  prepare  execution 
profil  -  execution  time 
kgmon  -  generate  a  dump  of  the  operating  syetem’s 
gprof  -  display  call  graph 
prof  -  display 
pxp  -  Pascal  execution 
end»  etext,  edata  -  last  locations  in 
ftp  -  file  transfer 
Ipc  -  line  printer  control 
Ipq  -  spool  queue  examination 
mt  -  magnetic  tape  manipulating 
pxref  -  Pascal  cross-reference 
units  -  conversion 
whereis  -  locate  source,  binary,  and/or  manual  for 

cb-C 

only)*  which  -  locate  a 
make  *  maintain 
nice  -  set 

get  priority,  set  priority  -  gct/set 
indent  indent  and  format  C 
assert  - 
lint  -  a  C 

lex  -  generator  of  lexical  analysis 
vgrind  -  grind  nice  listings  of 
xstr  -  extract  strings  from  C 
fbio  -  general 
if  -  general 
arp  -  Address  Resolution 
temp  -  Internet  Control  Message 
ip  -  Internet 
tep  -  Internet  Transmission  Control 
telnet  -  user  interface  to  the  TELNET 
udp  -  Internet  User  Datagram 
getprotobyname,  setprotoent,  endprotoeni  -  get 

inet  -  Internet 
rmt  •1'  remote  magtape 
protocols  - 

ftpd  -  DARPA  Internet  File  Transfer 
telnetd  -  DARPA  TELNET 
tftpd  -  DARPA  Trivial  Fite  Transfer 
trpt  -  transliterate 

mkproto  -  construct  a 
arithmetic  ~ 
false,  true  -* 
true,  false  - 


pty- 


diag  -  General- 
ungctc  - 
pushd: 

puts,  fputs  - 
putc,  putchar,  fputc,  putw  - 
logical  unit, 
on  a  stream, 
stream,  putc, 

putc,  putchar,  fputc, 


processing  language.  . 

processor . * . 

processor . 

processor . . . 

prof  -  display  profile  data . *  . . 

profil  -  execution  time  profile . 

profile,  monitor,  . 

profile . .  «  •  «  . 

profile  buffers.  ,  ,  ,  . . 

profile  data.  «  *  •  . . 

profile  data . . . 

profiler . . . 

program . .  .  .  ,  . 

program . 

program . 

program . 

program . . . 

program . 

program . 

program . . . * . 

program  beautifier . . 

program  file  including  aliases  and  paths  (esh  •  •  « 

program  groups . 

program  priority . 

program  scheduling  priority. . 

program  source . 

program  verification . . 

program  verifier.  . 

programs . 

programs . . . . 

programs  to  implement  shared  strings . 

properties  of  frame  buffers . 

properties  of  network  interfaces.  . . . 

Protocol . 

Protocol . 

Protocol . 

Protocol.  . . 

protocol.  . . 

Protocol . 

protocol  entry,  getprotoent,  getprotobynumber, 

protocol  family . .  . 

protocol  module . 

protocol  name  data  base.  •  «  •  . . 

Protocol  server.  . 

protocol  server.  . . 

Protocol  server . 

protocol  trace.  . . 

protocols  -  protocol  name  data  base . 

prototype  file  system . 

provide  drill  in  number  facts . 

provide  truth  values . 

provide  truth  values . 

prs  -  print  an  SCCS  file . 

ps  process  status . 

pseudo  terminal  driver.  . 

psignal,  sys^igUst  >  system  signal  messages.  .  •  . 

pstat  -  print  system  facts . 

pti  -  phototypesetter  interpreter . 

ptrace  -  process  trace,  . 

ptx  -  permuted  index . 

pty  -  pseudo  terminal  driver.  . 

purpose  stand-alone  utility  package . 

push  character  back  into  input  stream . 

push  shell  directory  stack . 

pushd:  push  shell  directory  stack . 

put  a  string  on  a  stream.  «  . . 

put  character  or  word  on  a  stream. 
putc,  fputc  -  write  a  character  to  a  FORTRAN 
putc,  putchar,  fputc,  putw  -  put  character  or  word 
putchar,  fputc,  putw  -  put  character  or  word  on  a 

puts,  fputs  -  put  a  string  ou  a  stream . 

putw  -  put  character  or  word  on  a  stream.  •  .  • 

pwd  -  print  working  directory  name.  . 

px  -  Pascal  interpreter.  . 

pxp  -  Pascal  execution  profiler . 

pxref  -  Pascal  cross-reference  program . 


awk{l) 

halt(8) 

m4(l) 

reboot(2) 

prof(l) 

profiI(2) 

monitor(3) 

profil(2) 

kgmon(8) 

gprof(l) 

prof(l) 

P*P(1) 

ea<l(3) 

ftp(lC) 

lpc(8) 

lpq(l) 

mt(l) 

pxref(l) 

anit9(l) 

whereid(l) 

cb(l) 

which(l) 

make(l) 

nice(SC) 

getpriority(2) 

indent(l) 

assert  (3) 

lint(l) 

lex(l) 

vgrind(l) 

X8tr(l) 

fbio(4S) 

if(4N) 

»n>(4P) 

icmp(4P) 

ip(4P) 

tcp(4P) 

telnet(lC) 

udp(4P) 

getprotoent(3N) 

inet(4F) 

rmt(8C) 

protocols  (5) 

ftpd(8C) 

tc!iietd(8C) 

tftpd(8C) 

trpt(8C) 

protocols(5) 

mkproto(8) 

arithmetic(6) 

false(l) 

trQe(l) 

prs(l) 

P»(l) 

pty(4) 

P8igna](3) 

pstat(8) 

pti(l) 

ptrace(2) 

ptx(i) 

pty(4) 

diag(8s) 

ungetc(3S) 

csh(l) 

C8h(l) 

puts(3S) 

putc(3S) 

putc(3F) 

putc(3S) 

putc(3S) 

puts(3S) 

putc(3S) 

pwd(l) 

px(l) 

pxp(l) 

pxref(l) 
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ipsqtit,  remqne  -  inseit /remove  dement  from  n 
Iprm  -  remove  joba  from  the  line  printer  apooling 

Ipq  -  apool 
qaort  - 
qaoii 


qnotn  -  munipnlnte  diak 
aetqnoti  -  en&ble/diaibte 

rntn  -  animnied 

fortune  -  print  a 
ranlib  -  convert  archivea  to 
rand,  arand  - 

random,  arandom,  initatate,  aetatate  *  better 
random  number  gener^or;  routine!  for  changing/ 

ratfor  - 

a  stream  to  a  remote  command. 


getpasa  - 
source: 
read,  readv  - 
readnewa  - 

wait/  fed,  evni,  exec,  exit,  export,  login,  newgrp, 

readlink  - 

directory  operations,  opendir, 
open  -  open  a  file  for 


new  arc  -  information  file  for 
/cd,  eva),  exec,  exit,  export,  login,  newgrp,  read, 

read, 

Iseek,  tell  -  move 
setregid-aet 
setreuid  -  set 
matloc,  free, 


rc  -  command  script  for  auto¬ 
reboot  - 
fastboot,  fasthatt  * 
newaliases  - 
reev,  xecvfrom,  lecvmag  - 
mail  -  send  and 
/bin/mait  -  send  or 
tturec- 
lecnewa  - 
recnewa  - 
rmail  -  handle  remote  mail 


rehash: 
utmp,  wtmp  -  login 
eyacc  -  modified  yacc  allowing  much  improved  error 

socket, 
socket,  reev, 
lecv,  lecvfrom, 
eval: 
re^comp, 
documents, 
pxref  -  Pascal  cross- 
index  to  a  bibliography  .br  lookbib  find 
refer  -  find  and  insert  literature 
re^comp,  rejexec  - 

comm  ~  select  or 


qsoit  -  quick  sort . . . 

qsoit  -  quicker  sort . . 

queue . . . 

queue.  •  •  . 

queue  examination  program . . 

quick  sort.  . . . 

quicker  sort.  . . 

quis  -  test  your  knowledge.  *  *  *  * . 

quot  -  summarise  file  system  ownership . 

quota  -  manipulate  disk  quotas.  «  •  *  . . 

quota# . 

quotas  on  a  file  system . . 

rain  -  animated  raindrops  display.  •  . . 

raindrops  display . .  •  • 

rand,  stand  ~  random  number  generator. 

random,  hopefully  interesting,  adage . 

random  libraries . 

random  number  generator . 

random  number  generator,  routines  for  changing/  «  «  * 
random,  srandom,  initstate,  setstate  -  better  •  •  *  •  « 

ranlib  -  convert  archives  to  random  libraries . 

ratfor  -  rational  Fortran  dialect . .  •  * 

rational  Fortran  dialect . 

rc  -  command  script  for  auto-ieboot  and  daemons.  •  ♦  * 
remd,  rresvport,  ruserok  -  routines  for  returning  ♦  «  «  * 

rep  -  remote  file  copy.  •  .  .  . . 

rdate  -  set  system  date  from  a  remote  host . 

read  a  password . 

read  commands  from  file . . . 

read  input.  . . . . 

read  news  articles . 

read,  readonly,  set,  shift,  times,  trap,  umask,  . 

read,  readv  -  read  input . 

read  value  of  a  symbolic  link.  •  *  .  . . 

readd ir,  telldir,  seekdir,  rewinddir,  closedtr  - . 

reading  or  writing,  or  create  a  new  file . 

readlink  -  read  vaiue  of  a  symbolic  link . 

readnews  -  read  news  articles . . . 

readnews(l)  and  checknews(l) . . 

readonly,  set,  shift,  times,  trap,  umask,  wxit  -/  •  .  «  • 

readv  -  read  input . 

read/write  pointer . 

real  and  effective  group  ID . 

real  and  effective  user  ID’s . 

realloc,  calloc,  efree,  alloca  -  memory  allocator. . 

reboot  -  reboot  system  or  halt  processor.  . . 

reboot  -  UNIX  bootstrapping  procedures . 

reboot  and  daemons . 

reboot  system  or  halt  processor . . . 

reboot/halt  the  system  without  checking  the  disks.  •  .  » 

rebuild  the  data  base  for  the  mail  aliases  file . 

receive  a  message  from  a  socket . 

receive  mail . . . 

receive  mail  among  users . * . 

receive  processed  news  articles  via  mail . 

receive  unprocessed  articles  via  mail . 

receive  unprocessed  articles  via  mail . 

received  via  uucp . . . 

recnewB  -  receive  unprocessed  articles  via  mail . 

recnews  -  receive  unprocessed  articles  via  mail . 

re.comp,  rejexec  -  regular  expression  handler . 

recompute  command  hash  table . 

records . . . .  ,  •  «  • 

recovery . 

reev,  recvfrom,  recvmsg  -  receive  a  message  from  a  *  •  « 
recvfrom,  recvmsg  -  receive  a  message  from  a  •  •  •  »  • 

recvmsg  -  receive  a  message  from  a  socket.  * . 

re-evaluate  shell  data . 

re.exec  -  regular  expression  handler . 

refer  -  find  and  insert  literature  references  in  «  •  *  »  » 

reference  program . * . 

references  in  a  bibliography.  /-  make  inverted  *  •  •  »  » 

references  in  documents . . 

regular  expression  handler  . 

rehash:  recompute  command  hash  table.  . 

reject  tines  common  to  two  sorted  files . 


qsoit(3F) 

q80Tt(3) 

insqnefS) 

Ipr^l) 

ipq(i)  ^ 

qsoit(3F) 

q80it(3) 

qoix(6) 

quot(8) 

quota(2) 

quota(2) 

Betquota(2) 

rain(6) 

rain(6) 

rand(3C) 

foiiune(6) 

ranlib(l) 

rand(3C) 

raDdom(3> 

random(3) 

rantib(l) 

ratfor(ll 

ratfor(l) 

rc(8) 

rcmd(3N) 

rcp(lC) 

rdate(8) 

getpa8S(3) 

C8h(l) 

read(2) 

readnew8(l) 

sh(l) 

read(2) 

readlink(2) 

dlrector^3) 

open(2) 

readlink(2) 

readnew8(l) 

ncw8rc(S) 

sh(l} 

read(2) 

tseek(2) 

8etregid(2) 

setreuid(2) 

mallocfS) 

rehoot(2l 

reboot(8) 

re(8) 

reboot(2) 

fastboot(8) 

newa1iases(8) 

rccv(2) 

mail(l) 

binmail(l) 

uurec(8) 

recnewsfl) 

recnew8(8) 

rmatl(8) 

recnew8(l) 

recnew8(8) 

regex(3) 

csh(l) 

ntmpISl 

eyacc(l) 

t^2) 

recvf2) 

recv(2) 

CBh(l) 

regex(S) 

refer(l) 

pxrcf(l) 

indxbil^l) 

refcr(l) 

Tegex(3) 

csh(l) 

comm(l) 
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lorder  -  find  ordering 
join  ^ 

-  notify  the  window  driver  of  the  physical 
eigpanee  -  atomically 
strip  -  remove  symbols  and 
leave  - 
calendar  - 

mserok  -  rontines  for  returning  a  stream  to  a 
rexec  -  retnm  stream  to  a 
rexeed  - 
rep- 

rdate  -  set  system  date  from  a 
unsead  -  send  a  file  to  a 
remote  - 
phones  - 
tlogia  - 
rlogind  - 
rmt  - 
rmail  -  handle 
rsh  - 
rshd  - 

tipi  ca  -  connect  to  a 
tmdel- 
nalink  - 
nadir- 
nnalias: 
flock  -  apply  or 
colrm- 
nnlink  - 
insqne,  remque  -  insert/ 
nnsetenv: 
mount,  nmonnt  -  mount  or 
Iprm  - 
dcroff  - 
expire  - 
unlimit: 
strip - 
nadir,  rm  - 
rm,  nadir  - 
insque, 


rename  - 
mv  -  move  or 

-  file  system  consistency  check  and  interactive 
trpfpe,  fpeent  -  trap  and 
while: 

uni4  -  report 
repeat:  execute  command 
yes  -  be 
df- 
iostal  - 
uniq- 
vmstat  - 
fseek,  ftell  - 
fscek,  ftell,  rewind  - 
'  notify. 

state, 
reset  - 
arp  -  address 
arp  -  Address 

getriimit,  setrlimit  -  control  maximum  system 
vlimit  -  control  maximum  system 
limit:  alter  per-process 
unlimit:  remove 
getrusage  -  get  Information  about 
vtimes  -  get  . information  about 
restore  -  incremental  file  system 

suspend:  suspend  a  shell, 
getarg,  iaige  - 
idate,  itime  - 
flmin,  flmax,  dflmin,  dflmax,  inmax  - 


relation  for  an  object  library . lorder^l) 

relational  database  operator . joiu(l) 

relationships  of  screens,  adjacentscreens  . adjacentscreens(l) 

release  blocked  signals  and  wait  for  interrupt . 8igpau3e(2) 

relocation  bits.  ,  . . .  strip(l) 

remind  you  when  you  have  to  leave.  . !eave(l) 

reminder  service . . . calendai(l) 

remote  -  remote  host  description  file.  remote(5) 

remote  command,  remd,  . . rcmd(3N) 

remote  command . rexec(SN) 

remote  execution  server,  •  •  .  . . rexecd(8C) 

remote  file  copy.  . . rcp(lC) 

remote  host . rdate{8) 

remote  host . uuscnd(lC) 

remote  host  description  file . remote(5) 

remote  host  phone  number  data  base . .  phones(5) 

remote  login . rlogin(lC) 

remote  lo|pn  server. . rlogmd(8C) 

remote  magtape  protocol  module . rmt(8C) 

remote  mail  received  via  uucp . . . .  rmail(8) 

remote  shell . rsh(lC) 

remote  shell  server . *  r8hd(8C) 

remote  system . tip(lC) 

remove  a  delta  from  an  SCCS  file . .  rmdel(l) 

remove  a  directory  entry . unlink(3F) 

remove  a  directory  file . rmdir(2) 

remove  aliases . csh(l) 

remove  an  advisory  lock  on  an  open  file . flock(2) 

remove  columns  from  a  file.  . colm(l) 

remove  directory  entry . unlink(2) 

remove  element  from  a  queue . in5que(3) 

remove  environment  variables . C8h(l) 

remove  file  system . mount(2) 

remove  jobs  from  the  line  printer  spooling  queue . Ipnn(l) 

remove  nrolf,  troff,  tbl  and  cqn  constructs . dcroff(l) 

remove  outdated  news  articles . . . expire(8) 

remove  resource  limitiations.  . . C8h(l) 

remove  symbols  and  relocation  bits . 8trip(l) 

remove  funlink)  directories  or  files . rmdirfl) 

remove  (unlink)  files  or  directories.  .  .  * . m(l) 

remque  -  insert/remove  element  from  a  queue . iu8que(3) 

rename  -  change  the  name  of  a  file. . *  rename(2) 

rename  -  rename  a  file . rename(3F) 

rename  a  file . rename(3F) 

rename  files . mv(l) 

rcnice  -  alter  priority  of  running  processes . renicefS) 

repair,  fsck  . . f8ck(8) 

repair  floating  point  faults . tipfpe(3F) 

repeat  commands  conditionally . «  C8h(l) 

repeat:  execute  command  repeatedly . C8h(l) 

repeated  lines  in  a  file . . . uiiiq(l) 

repeatedly.  c  . . C8h(l) 

repetitively  affirmative . y«(l) 

report  free  disk  space  on  file  systems . df(l) 

report  I/O  statistics . .  lost  at  (8) 

report  repeated  lines  in  a  file . uniq(l) 

report  virtual  memory  statistics . vm8tat(8) 

reposition  a  file  on  a  logical  unit . .  •  •  f8eek(3F ) 

reposition  a  stream . . . fseek(3S) 

request  immediate  notification . C8h(l) 

reset  -  reset  the  teletype  bits  to  a  sensible . rcsetfl) 

reset  the  teletype  bits  to  a  sensible  state . resetfl) 

resolution  display  and  control . .  arp(8C) 

Resolution  Protocol . .  arp(4P) 

resource  consumption . getriimit(2) 

resource  consumption . vlimit(3C) 

resource  (imitations.  «  *  * . csh(l) 

resource  limitiations . csh(l) 

resource  utilization . getrusage(2) 

resource  utilization . . . vtimes(3C) 

restore . re5torc(8) 

restore  -  incremental  file  system  restore . re8tore{8) 

resuming  its  superior . CBh(l) 

return  command  line  aiguments . getar^SF) 

return  date  or  time  in  numerical  form . idate(3F) 

return  extreme  values . raugc(3F) 
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permuted  Inde* 


Kxec- 

loc- 

rcmd,  rrcavport,  mserok  -  routines  for 

rev  - 

lastcomni  -  show  last  commands  executed  in 

col  -  filter 
fseck,  ftell, 
opendir,  readdir,  telldir»  seekdir, 


stremp,  stmernp,  strepy,  strnepy,  strlen,  index, 

objects,  index, 


nndir, 


no, 


chase  -  Try  to  escape  to  killer 

pow,  iqrt  -  exponential,  lof^arithm,  power,  square 

chroot  -  change 


fsplit  -  split  a  mnlth 
tgoto,  tpnts  -  terminal  independent  operation 
setstate  -  better  random  number  generator, 
command,  remd,  nesvpoit,  ruscrok  - 
-  system  supporting  for  local  network  packet 
packet  routing, 
routed  -  network 
route  -  manually  manipulate  the 
itom,  madd,  msub,  mult,  mdiv,  min,  mout,  pow,  ged, 
stream  to  a  remote  command,  remd, 


nice,  nohup  - 
nohup: 
nice: 
roffbib  - 

crontab  -  table  of  times  to 
score  -  get  core  images  of 
renice  -  alter  priority  of 

remote  command,  remd,  rresvport, 


ec  -  3Com  10  Mb/ 
en  -  Sun  S  Mb/ 
pr  -  print  fil^ 


savecore  - 
system, 
brk, 

St  -  Driver  for  Sysgen 
scandir,  alphasort  - 

conveision. 
awk  -  pattern 
ss  -  silog  8530 

ede  -  change  the  delta  commentaxy  of  an 
comb  -  combine 
delta  -  make  a  delta  (change)  to  an 
get  -  get  a  version  of  an 
pts  -  print  an 
nndel  -  remove  a  delta  from  an 
scesdiff  -  compare  two  versions  of  an 
sees  file  -  format  of 


return  stream  to  a  remote  command. 

return  the  address  of  an  object . .  .  .  ♦  . 

returning  a  stream  to  a  remote  command . 

rev  -  revene  lines  of  a  file . 

reverse  lines  of  a  file . . 

reverse  order . . . . . 

reverse  paper  motions . .  • 

rewind  -  reposition  a  stream.  . . 

rewinddir,  closedir  -  directory  operations. 

rexec  -  return  stream  to  a  remote  command.  «  •  *  ♦  » 

rexecd  -  remote  execution  server . 

rindex  -  string  operations,  streat,  stmeat,  . 

rindex,  Inblnk,  len  -  tell  about  character  ••••«». 

riogin  -  remote  login . .  •  • 

riogind  -  remote  login  server . 

rm  -  remove  (unlink)  directories  or  fifes.  . . 

rra,  rmdir  -  remove  (unlink)  files  or  directories.  .  .  .  ^ 
rmail  -  handle  remote  mail  received  via  uuep.  •  «  *  »  * 

rmdel  -  remove  a  delta  from  an  SCCS  file . 

rmdir  -  remove  (unlink)  files  or  directories. 

rmdir  -  remove  a  directory  file.  . . 

rmdir,  rm  -  remove  (unlink)  directories  or  files . 

rmt  -  remote  magtape  protocol  module. . *  «  . 

robots . 

roifbib  -  run  off  bibliographic  database . 

root,  exp,  log,  loglO,  . 

root  directory.  .  . . * . . 

route  -  manually  manipulate  the  routing  tables.  «... 

routed  -  network  routing  daemon . 

routine  Fortran  file  into  individual  files . 

routines,  tgetent,  tgetnum,  tgetffag,  tgetstr, . 

routines  for  changing  generators,  /initstate, . 

routines  for  returning  a  stream  to  a  remote  *.«.«. 

routing,  routing  ...  * . . 

routing  -  system  supporting  for  local  network  . 

routing  daemon . 

routing  tables . . 

rpow  -  multiple  precision  integer  arithmetic . 

rresvport,  mserok  -  routines  for  retnming  a . 

rsh  -  remote  shell . 

rshd  -  remote  shell  server . 

mn  a  command  at  low  priority  (sh  only) . 

run  command  immune  to  hangups . 

run  low  priority  process . . . . 

run  off  bibliographic  database.  . . . 

run  periodic  jobs . 

running  processes . 

mnning  processes . . 

mptime  -  show  host  status  of  local  machines.  •  *  «  •  « 
mserok  -  routines  for  returning  a  stream  to  a  «  .  «  «  • 

rwho  -  who’s  logged  in  on  local  machines . 

rwhod  -  system  status  server.  . 

8  Ethernet  interface . 

B  experimental  Ethernet  interface . .  «  « 

s),  possibly  in  multiple  columns . 

sa,  aceton  -  system  accounting.  . . 

sact  -  print  current  SCCS  file  editing  activity. . 

sail  -  multUttser  wooden  ships  and  iron  men . . 

save  a  core  dump  of  the  operating  system.  .«««..« 

savecore  -  save  a  core  dump  of  the  operating  . 

sbrk  -  change  data  segment  site . 

SC  4000  (Archive)  Tape  Controller. . 

scan  a  directory.  . . 

scandir,  alphasort  -  scan  a  directory.  «««•««•«« 

scanf,  fsca^,  sscani  -  formatted  input  . 

scanning  and  processing  language . . 

SCO  serial  comunications  driver.  •  «  •  . . 

sees  -  front  end  for  the  .SM  SCCS  subsystem . 

SCCS  delta . 

SCCS  deltas.  . . . 

SCCS  file . 

SCCS  file.  . . 

SCCS  file.  .  .  .  . . 

SCCS  file . 

SCCS  file . 

SCCS  file . 


rexec(3N) 

loc(3F) 

rcmd(3N) 

rev(l) 

re^l) 

|&5tcomm(l) 

col(l) 

fseek(SS) 

directories) 

rexec(3N) 

rexecd(8C) 

ftring(3) 

index(3P) 

rlogin(lC) 

rlogind(8C) 

rmdir(I) 

rm(l) 

rmail(B) 

rmdel(l) 

rm(l) 

rmdir{2i 

rmdir(l) 

rmt(8C) 

chase(6) 

roffbib(l) 

exp(3M) 

chroot(2) 

route(8C) 

ronted(8C) 

fspllt(l) 

teimcap(3X) 

random(3) 

rcmd(3N) 

routing{4N) 

routing(4N) 

routed(8C) 

route(8C) 

mp(3X) 

rcmd(3N) 

r8h(lC) 

rBhd(8C) 

Dlce(l) 

CBh(l) 

C8h(l) 

roffbib(l) 

crontab(5) 

gcore(l) 

renice(8) 

mptlme(lO) 

rcmd(3N) 

rwbo(lC) 

rwhod(8C) 

ec(4S) 

en(4S) 

pi(i) 

•*(8) 

sact(l) 

sait(6) 

savecore(8) 

8avecore(8) 

brk(2) 

et(4S) 

8candir(3) 

Bcandii($) 

scanf(3S) 

awk(l) 

ss(4S) 

SCC8(l) 

cdc(l) 

comb(l) 

delta(l) 

getfl) 

prs(l) 

rmdel^ 

8CC8diff(l) 

8CC8file(5) 
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un^ti  -  undo  a  previona  get  of  an 
val  -  validate 
aact  -  print  current 
admtn  -  create  and  administer 
8CC8  -  front  end  for  the  .SM 


alarm  - 

gctprierity,  setpriority  -  get/set  program 
clear  -  clear  workstation  or  terminal 
curses  - 
ex.  vi  - 

the  window  driver  of  the  physical  relationships  of 
adbgen  -  generate  adh 

re  -  command 
onintr:  process  interrupts  in  command 
Controllers, 
grep;  egrep,  fgrep  - 
xsend,  xget,  enroll  - 

operations,  opendir,  readdir,  teltdlr» 
brk,  sbric  -  change  data 

comm  - 
case: 
uusend  - 
send,  sendto,  sendmsg  - 
kill- 
kill- 
mail  - 
sendmail  - 
scndnews  - 
/bin/mail  - 
socket. 

kill  - 
killpg^ 

aliases  -  aliases  hie  for 
send,  sendto, 
send, 

reset  -  reset  the  teletype  bits  to  a 
oct  -  Centr^  Data  octal 
IS  -  lilog  8530  SCO 
comsat  -  biff 

ftpd  -  DARM  Internet  File  Transfer  Protocol 
rexecd  -  remote  execution 
riogind  -  remote  login 
nhd  -  remote  shell 
rwhod  -  system  status 
telnetd  -  DARPA  TELNET  protocol 
tftpd  -  DARPA  Trivial  File  Transfer  Protocol 
timed  -  DARPA  Time 
serven  -  inet 

calendar  **  reminder 

inetd  •  internet 
logout:  end 

script  *  make  typescript  of  terminal 
ascii  -  map  of  ASCII  character 
stty,  gtty  - 
sigstack  - 

sigsetmask  - 
gettimeofday,  scttimcofday  -  get/ 
umask  - 
ntime- 
utimes  - 
setgroups  - 
gethostname,  sethostname  -  get/ 
getsockopt,  setsockopt  -  get  and 
hostname  - 
sctpCT  “ 
nice  - 


sees  file . 

sees  file . 

secs  file  editing  activity . 

secs  files . 

secs  subsystem . 

scesdiff  -  compare  two  veisions  of  an  SCCS  file. 

scesfile  -  format  of  SCCS  file . 

schedule  signal  alter  specified  time . 

scheduling  priority . . . 

screen . .  .  .  . . .  • 

screen  functions  with  ^^optimar*  cursor  motion, 
screen  oriented  (visual)  display  editor  based  on 

screens,  adjacentscreens  -  notify . 

script . 

script  '  make  typescript  of  terminal  session.  * 

script  for  auto-reboot  and  daemons . 

scripts . 

sd  -  Disk  driver  for  Adaptec  ST-506  Disk  ,  • 

search  a  file  for  a  pattern . 

secret  mail . 

sed  -  stream  editor.  *  •  •  . . 

seekdir,  rewinddir,  closcdir  -  directory  .  .  • 

segment  site . . 

select  -  synchronous  I/O  multiplexing.  •  .  . 
select  or  reject  lines  common  to  two  sorted  files, 

selector  in  switch . 

send  a  file  to  a  remote  host.  •  . . 

send  a  message  from  a  socket . 

send  a  signal  to  a  process . 

send  a  signal  to  a  process,  or  terminate  a  process 

send  and  receive  mail . 

send  mail  over  the  internet . 

send  news  articles  via  mail . 

send  or  receive  mail  among  useiu . 

send,  sendto,  sendmsg  -  send  a  message  from  a 

send  signal  to  a  process . 

send  signal  to  a  process  group . 

sendmail . 

sendmail  -  send  mail  over  the  internet.  .  .  . 
sendmsg  -  send  a  message  from  a  socket.  •  • 
sendnews  -  send  news  articles  via  mail.  .  «  • 
sendto,  sendmsg  -  send  a  message  from  a  socket. 

sensible  state . 

serial  card . 

serial  comunications  driver . 

server.  . . . 

server.  . 

server.  . 

server.  . 

server.  . 

server.  . 

server.  . . . 

server.  . 

server.  . 

server  data  base . 

servers  inet  server  data  base. 

service . 

services  -  service  name  data  base . 

services  daemon . 

session . 

sessiod . .  .  •  .  . 

set.  . . 

set  and  get  terminal  state . 

set  and/or  get  signal  stack  context . 

set:  change  value  of  shell  variable . 

set  current  signal  mask . 

set  date  and  time.  . 

set  file  creation  mode  mask . 

set  file  times . 

set  file  times.  . 

set  group  access  list.  •  . . 

set  name  of  current  host . 

set  options  on  sockets . 

set  or  print  name  of  current  host  system.  •  . 

set  process  group.  «  .  .  •  . . 

set  program  priority . 


.  .  .  .  unget(l) 

.  .  .  .  val(l) 

,  .  .  »  8act(l) 

,  ,  .  .  admin(l) 

,  .  ,  ,  8ccs(l) 

»  .  ,  ,  sccsdiff(l) 

•  •  .  .  8CC8file(5) 

,  .  •  .  alarm(SC) 

•  .  .  .  getpriority(2) 

•  .  ,  ,  clear(l) 

,  ,  .  ,  cur8cs(3X) 

.  .  .  .  vi(l) 

.  .  .  .  adjacentscreens(l) 

«  »  •  .  adbgen(8) 

«  .  «  •  script(l) 


•  •  •  .  sd(4S) 

.  .  ,  ,  grep(l) 

•  ♦  .  ,  X8end(l) 

4  «  •  .  sed(l) 

,  •  4  •  direct oiy(3) 

4  4.4  brk(2) 

4  4  4  4  sele€t(2) 

4  4  4  4  comm(l) 

4  4  4  *  C8h(l) 

4  4  4  4  uusend(lC} 
44.4  8end(2) 

4  4  4  4  kill(3F) 

4  4  4  kill(l) 

4.4.  mail(l) 

4  4  4  .  8endmail(8) 

4  4  4  4  sendnew8(8) 
.44.  binmail(l) 

4  4  4  4  8end(2) 

4  4  4  4  kill(2) 

4  4  4  4  killp^2) 

4  4  4  4  a]ia8es(5) 

•  4  4  4  8endmaii(8) 

4  4  4  4  8end(2) 

4  4  .  4  8endnews(8) 

4  4  4  4  send(2) 

4  4  4  .  reset(l) 

.4,4  oct(4S) 

4  4  4  4  sa(4S) 

4  4.4  com8at(8C) 

4  4  4  4  ftpd(8C) 

4.44  rcxccd(8C) 

4  4  4  4  rtogiDd(8C) 

4  4  4  4  r8hd(8C) 

4  4  4  4  rwhod(8C) 

4.44  telnet  d(8C) 

4  4  4  4  tftpd(8C) 

4.44  timed(8C) 

4  4  4  4  Beiveis(5) 

4  .  4  4  8erver8(5) 

4  4  4  4  calendaz^l) 

4  4  4  4  8ervices(5) 

4  4  4  4  inetd(8C) 

.  4  4  4  C8h(l) 

4  4  4  4  script(l) 

4  4.4  ascii(7) 

4  4  4  4  8Uy(3C) 

4  .  4  4  8lg3tack(2) 

4  4  4  4  C8h(l) 

4  4  4  .  8ig8etma8k(2) 

•  4  4  4  gettimeofday(2) 
4  4.4  umask(2) 

4  4  4  4  utime(3C) 

4  4  4  *  utimes(2) 

4  4  4  4  setgroups  (2) 
4.44  getho8tiiame(2) 

•  4  4  4  getsockopt(2) 
....  hostname(l) 

4  .  4  4  8etpgrp(2) 

4  4  4  4  nice(3C) 
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l^etpriorityi  sctpriority  -  get/ 
setregid  - 
>etrettid  - 

/exec,  exit,  export,  login,  newgrp,  rend,  rendonty, 

rditc  - 
getty  - 
itty- 
dnte  *  display  or 
setcaid,  setniid,  setgid,  letegid,  letrgid  - 
ulimit  *  get  tud 
getitimer,  sctitimer  -  get/ 
aeteiiT: 
to  4  etreim. 
strexm.  setbuf, 
setnid,  aetenid,  aetmid,  letgid, 

user  4nd  grottp  ID,  aetnid, 
file/  getfaent,  getfaapec,  getfafile,  getfatype, 
aetnid,  aeteoid,  aetmid, 
getgrent,  getgrgid,  getgmam, 

getlioatent,  getboatbynddr,  gethoatby&ime, 
getboatnftine, 
getitimer, 

crypt, 
aetbof,  aetbaffer, 
getnetent,  getnetbynddr,  getnetbynime, 

getpriority, 

getprotoent,  getprotobynnmber,  getprotobynime, 
getpwent,  getpwvid,  getpwaom, 


aetnid,  aetenid,  aetmid,  aetgid,  aetegid, 
conanmptioB.  getrlimit, 
gronp  ID.  aetnid,  aetenid, 
getaervent,  getaervbyport,  getaervbyttxme, 
getiockopt, 

rontinea  for  cbnnging/  random,  arandom,  initatate, 

gettimeofday, 
-  aet  naer  and  group  ID. 
cd,  eval,  exec,  exit,  export,  login,  newgrp,  read,/ 
nice,  nobnp  -  mn  a  command  at  tow  priority  ( 
-  extract  atiinga  from  C  programa  to  implement 
cbab  -  change  defanlt  login 
exit:  leave 
rah  -  remote 
ayatem  -  iaane  a 
cab  *  a 
eval:  re-evalnate 
popd:  pop 
pnabd:  pnab 
atiaa: 

ana  pend:  anapend  a 
rabd  -  remote 
aet:  change  value  of 
O:  arithmetic  on 
unaet:  diacard 
exec:  oveiiay 

exit,  export,  login,  newgrp,  read,  readonly,  aet, 
sail  -  multi-naer  wooden 
groupa  - 
ruptime  - 
uptime  - 
laatcomm  - 
netatat  - 
shutdown  - 


connection. 

login  - 
pause  -  atop  until 
signal  -  change  the  action  for  a 


aet  program  scheduling  priority . 

set  real  and  effective  group  ID . 

set  real  and  effective  user  1D*8 . 

set,  shift,  times,  trap,  umaak,  watt  -  command/  *  *  *  . 

aet  ayatem  date  from  a  remote  host.  «  . . .  « 

aet  terminal  mode . 

set  terminal  options . . . 

set  the  date . . 

set  user  and  group  ID.  setuid, . 

set  nier  limiti . . . .  « 

set  value  of  interval  timer . 

set  variable  in  environment . .  •  . 

setbnf,  set  buffer,  letlinebuf  -  assign  buffeiing  . 

setbuffer,  setlinebuf  -  assign  buffering  to  a . 

setegid,  setrgid  -  set  naer  and  group  ID. . *  . 

setenv:  set  variable  in  environment . 

leteuid,  setrutd,  setgid,  setegid,  setrgid  -  set  . . 

setfsent,  endfsent  «  get  file  system  descriptor  . 

setgid,  setegid,  setrgid  -  set  user  and  group  ID.  •  •  «  • 

aetgrent,  endgrent  -  get  group  file  entry . 

aetgroups  -  aet  group  access  list . .  «  *  «  * 

sethostent,  endhostent  -  get  network  host  entry.  • 

•ethoatname  -  get/aet  name  of  current  host . 

aetitimer  -  get/set  value  of  interval  timer.  * . 

aetjmp,  longjmp  -  non-local  goto.  *  *  *  «  «  «  •  •  •  * 

actkey,  encrypt  -  DBS  encryption . 

setlinebnf  -  assign  buffering  to  a  stream . 

setnetent,  endnetent  -  get  network  entry.  .  . . 

setpgrp  -  set  process  group . 

setpriority  -  get/set  program  scheduling  priority.  •  .  *  « 

setprotoent,  endprotoent  -  get  protocol  entry . 

setpwent,  endpwent  -  get  password  file  entry . 

setquota  -  enable/diaabte  quotas  on  a  file  system.  •  «  • 
setregid  -  set  real  and  effective  group  ID. 

aetreuid  -  aet  real  and  effective  user  ID*s . 

setrgid  -  set  user  and  group  ID . 

setrlimit  -  control  maximum  system  resource  . 

aetruid,  aetgid,  setegid,  setrgid  -  set  user  and  . 

letservent,  endservent  -  get  service  entry . 

setsockopt  -  get  and  set  options  on  sockets . 

setstate  -  better  random  number  generator; 

settimeofday  -  get/set  date  and  time . 

setuid,  seteuid,  aetruid,  aetgid,  setegid,  setrgid  . 

sh,  for,  case,  if,  while, .,  break,  continue . 

sh  only) . 

shared  strings,  xatr  . . . 

ahett . 

•hell . 

•hell . 

shell  command . 

shell  (command  interpreter)  with  C-tike  syntax . 

shell  data . . . 

shell  directory  stack . 

shell  directory  stack.  . . . 

shell  macros . . . 

shell,  resuming  its  superior.  . 

shell  server.  . .  * 

shell  variable.  . . . . 

shell  variables . 

shell  variables . . 

shell  with  specified  command . 

shift:  manipulate  argument  list.  «  «  * . 

shift,  times,  trap,  umask,  wait  -  command/  /exec,  •  *  • 

ships  and  iron  men. . . 

show  group  memberahipa . 

show  boat  status  of  local  machines . 

show  how  long  system  has  been  up . . 

show  last  commands  executed  in  revem  order. . 

show  network  status . .  . 

shut  down  part  of  a  full-duplex  connection . 

shutdown  -  close  down  the  system  at  a  given  time.  •  •  . 

shutdown  -  shut  down  part  of  a  full-duplex  . 

sigblock  -  block  signals . 

sign  on . . . .  ,  *  *  , 

signal . . . . . 

signal . .  .  «  * 


getpriority(2) 

setrcgid(2) 

8etreuid(2) 

sh(l) 

rdate(8) 

gett3r(8) 

#tty(l) 

daie(l) 

setQid(3) 

utimit(3C) 

getitimej(2) 

C8h(l] 

setbuf(SS) 

setbnf(3S) 

setuid(3) 

C8h(l) 

8etuid(3) 

getfsent(3) 

8etaid(3) 

getgrent(3) 

ietgTonps(2) 

gethostent(3N) 

geiho8tname(2) 

getitimei(2) 

setjmpfS) 

crypt(3) 

8etbuf(3S) 

getttetent(3N) 

Bctpgrp(2) 

getpriority(2) 

gctprotoent(3N) 

getpwent(3) 

setquota(2) 

8etregid(2) 

setreaid(2) 


8etnid(3) 

getriimit(2) 

Betuid(3) 

get8crvcnt(3N) 

get8ockopt(2) 

random(3) 

g6tttmeofday(2) 

setuid(3) 

•Ml) 

nice(l) 

X8tl(l) 

chsh(I) 

csh(l) 

XBh(lC) 

8ystem(3) 

C8h(l) 

C8h(l) 

csMl) 

csh(l) 

C8h(l) 

C8h(l) 

r8hd(8C) 

C8h(l) 

C8h(l) 

C8h(l) 

csh(l) 

C8h(l) 

A{1) 

8ail(6) 

groap9(l) 

ruptime(lC) 

uptime(l) 

lastcomin(l) 

net8tat(8) 


shutdown(2) 

shutdown(8) 

shutdown(2) 

8igblock(2) 

login(l) 

pau8e(3C) 

8ignat(3F) 
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alarm  -  schedule 
eiS&aJ  -  simplified  software 
sigvec  -  software 
sissetmask  -  set  current 
psignal,  sysjiglist  *-  system 
sigstack  -  set  and/or  get 
kill  -  send 
kill  -  send  a 
killpg  -  send 
kill  -  send  a 
sigblock  -  block 
slgpanse  -  atomically  release  blocked 
wait  for  interrupt. 


signal  - 

trigonometric  functions. 

null  *  data 

brk,  sbrk  -  change  data  segment 
getdtablesise  -  get  descriptor  table 
getpagesiie  >  get  system  page 
pagesife  -  print  system  page 

siie- 


sees  -  front  end  for  the 
Ip  -  Disk  driver  for  Interphase  218D 
xy  -  Disk  driver  for  Xylogics 
spline  -  interpolate 

snake, 

accept  -  accept  a  connection  on  a 
bind  -  bind  a  name  to  a 
connect  -  initiate  a  connection  on  a 
listen  -  listen  for  connections  on  a 
reev,  iecvfrom»  recvmsg  -  receive  a  message  from  a 
send,  sendto,  sendmsg  -  send  a  message  from  a 

getsockname  -  get 

getsockopt,  setsockopt  -  get  and  set  options  on 
socketpair  -  create  a  pair  of  connected 

lo  - 

signal  -  simplified 
sigvec  - 
Canfield,  cfscores  tbe 
qsort  -  quicker 
qsort  -  quick 
tsoit  -  topological 

soribtb  - 
sort  - 

comm  -  select  or  reject  lines  common  to  two 
look  find  lines  in  a 
soetim  -  eliminate 
indent  -  indent  and  format  C  program 
*  create  an  error  message  file  by  massaging  C 
whereis  -  locate 

mem,  kmem,  mbmem,  mbio  -  main  memory  and  I/O 
line,  circle,  arc,  move,  coni,  point,  linemod, 
df  -  report  free  disk 
expand,  unexpand  -  expand  tabs  to 
way.  vfork- 
exec:  overlay  shell  with 
head  -  display  first  few  lines  of 
truncate,  ftruncate  -  truncate  a  file  to  a 
alarm  -  schedule  signal  after 


signal  -  change  the  action  for  a  signal . 

signal  -  simplified  software  signal  facilities . 

signal  after  specified  time . .  * 

signal  facilities . 

signal  facilities.  .  . . 

signal  mask . 

signal  messages . 

signal  stack  context.  . . 

signal  to  a  process . .  .  » 

signal  to  a  process . 

signal  to  a  process  group . 

signal  to  a  process,  or  terminate  a  process . 

signals . 

signals  and  wait  for  interrupt . 

sigpause  -  atomically  release  blocked  signals  and  «  «  •  « 

sigsetmask  -  set  current  signal  mask . 

sigstack  -  set  and/or  get  signal  stack  context . 

sigvec  -  software  signal  facilities . 

simplified  software  signal  facilities . 

sin,  cos,  tan,  asin,  acos,  atan,  atan2  - . 

slab,  cosb,  tanh  -  hyperbolic  functions . . 

sink.  . . 


space . . . 

space,  closepi  -  graphics  interface,  /label . 

space  on  file  systems . 

spaces,  and  vice  versa . .  .  .  » 

spawn  new  process  in  a  virtual  memory  efficient  «  .  .  . 

specified  command . 

specified  files . 

specified  length . . . 

specified  time . 


file.  . . 

site . 

site . . 

site.  . 

site  -  sise  of  an  object  file . 

site  of  an  object  file . . . 

sleep  -  suspend  execution  for  an  interval.  .  • 
sleep  -  suspend  execution  for  an  interval.  •  • 
sleep  -  suspend  execution  for  interval.  .  .  . 

.SM  sees  subsystem . 

SMD  Disk  eontroller . 

SMD  Disk  Controllers . 

smooth  enrve . 

snake,  snscore  -  display  ebase  game . 

snscore  -  display  chase  game . 

socket . 

socket . 

sookel.  •  «  •  . . 

socket.  . . 

socket . 

socket . 

socket  -  create  an  endpoint  for  communication. 

socket  name . .  •  . . 

socketpair  -  create  a  pair  of  connected  sockets. 

sockets . 

sockets . . . 

soelim  -  eliminate  .so^s  from  nroff  input.  «  • 

software  loopback  network  interface . 

software  signal  facilities . . 

software  signal  facilities.  . 

solitaire  card  game  canfield.  »  . . 

son . 

son,  . . . 

soH.  . . 

sort  -  sort  or  merge  files . 

sort  bibliographic  database . 

sort  or  merge  files . . . 

Bortbib  -  sort  bibliographic  database . 

sorted  files . 

sorted  list . . . 


source.  . . 

source,  mkstr  •  . . 

source,  binary,  and/or  manual  for  program, 
source:  read  commands  from  file . 


8ignal(3F) 

8ignal(3) 

a!arm(3C) 

8ignal(3) 

8lgvec(2) 

8ig9etmask(2) 

p8ignal(3) 

8igatack(2) 

kill(2) 

kilI(3F) 

killpg(2) 

kill(l) 

sigblock(2) 

sigpau8e(2} 

sigpause(2) 

sigsetmask(2) 

sig9tack(2) 

8igvec(2) 

Bignal(3) 

8in(3M) 

8lnh(3M) 

null(4) 

brk(2) 

get<ltable8isef2) 

getpage8ize(2) 

pagesiie(l) 

8ize(l) 

8ize(l) 

sleep(l) 

slccp(3F) 

8leep(3) 

SCC3(l) 

ip(4S) 

xy(4S) 

8p!ine(lG) 

8nake(6) 

8nake(6) 

accept(2) 

bind(2) 

con]iect(2) 

Ii8ten(2) 

recv(2) 

8end(2) 

socket(2) 

get80ckname(2) 

socket  pai  if  2) 

get  sock  opt  (2) 

80cketpair(2) 

soe]im(l) 

.  V 

signal(3) 

sigvcc(2) 

ca2ifield(6) 

qsott(3) 

q8ort(3F) 

tsort(l) 

8ort(l) 

sortbib(l) 

sort(l) 

8ortbib(l) 

comm(l) 

look(l) 


indent(l) 

mkstifl) 

whcreis(l) 

C8b(l) 

mem(4S) 

plot(3X) 

df(l) 

cxpand(l) 

vfork(2) 

C3h(l) 

head(l) 

tnnicate(2) 

alarm(3C) 
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ftlarm  -  execute  &  subrouttne  after  a 
ewapon  - 


spell, 

spell,  spellin,  spettout  -  fiud 
spell,  spellio, 


split  - 
files,  fsplit  '• 
frexp,  Idexp,  modf  - 
uucleafi  -  nacp 
Ipq- 

Ipnn  -  remove  joba  from  tbe  line  printer 
priutf,  fprintf, 
exp,  log,  loglO,  pow, 
loglO,  pow,  sqrt  -  expoaeatial,  logiritbm,  power, 

rand, 

number  generator,  routines  for  changing/  random, 

scanf,  fscanf, 
Controller 
sd  -  Disk  driver  for  Adaptec 
popd:  pop  shell  directory 
pushd:  push  shell  directory 
sigstack  -  set  and/or  get  signal 
imemtest  - 
gxtest  - 
diag  *  GeneraI*purpose 
stdio  - 

htable  -  convert  NIC 
tee  -  copy 

reset  -  reset  the  teletype  bits  to  a  sensible 
stty,  gtty  -  set  and  get  terminal 
fsync  -  synchronise  a  file's  in-core 
if:  conditional 
fstab  - 

hashstat:  print  command  hashing 
iostat  -  report  I/O 
pexfmon  -  graphical  display  of  general  system 
vmstat  -  report  virtual  memory 
exit  -  terminate  process  with 
net  St  at  -  show  network 
ps  -  process 
stat,  Istat,  fatat  -  get  file 
ferror,  feof,  clearerr,  fileno  -  stream 
mptime  -  show  host 
rwhod  -  system 


wait,  wait 3  -  wait  for  process  to  terminate  or 

halt- 
pause  - 
[check  -  file  system 
subroutines,  dbminit,  fetch, 
strlen,  index,  rindex  -  string  operations, 
rindex  string  operations,  streat,  strncat, 
operations,  streat,  strncat,  stremp,  stmemp, 
fclose,  fliush  -  close  or  flush  a 
fopen,  free  pen,  fdopen  -  open  a 
fseek,  ftell,  rewind  -  reposition  a 
fgetc,  getw  -  get  character  or  integer  from 
gets,  fgets  -  get  a  string  from  a 
putchar,  fputc,  putw  -  put  character  or  word  on  a 
puts,  fputs  -  put  a  string  on  a 
setbuffer,  setlinebuf  -  assign  buffering  to  a 
nngetc  -  push  character  back  into  input 

sed  - 

ferror,  feof,  clearerr,  fileno  - 
rresvpori,  ruscrok  -  routines  for  returning  a 
rexec  -  return 
ar  “  Archive  1/4  inch 
gets,  fgets  '  get  a 
puts,  fputs  -  put  a 
bcopy,  bemp,  bzero,  ffs  -  bit  and  byte 


specified  time.  . . . 

specify  additional  device  for  paging  and  swapping.  •  *  • 

spell,  speltin,  spellont  -  find  spelling  errors . . 

spellin,  spellout  -  find  spelling  errors . 

spelling  . . . . .  ♦  •  .  . 

spellout  -  find  spelling  errors . . 

spline  -  interpolate  smooth  curve . 

split  -  split  a  file  into  pieces.  •  .  .  . . 

split  a  file  into  pieces . *  .  ,  •  . . 

split  a  multhrouiiue  Fortran  file  into  individual  «  «  •  « 

split  into  mantissa  and  exponent . .  «  »  «  . 

spool  directory  clean-np . . . 

spool  qneue  examination  program . 

spooling  queue . 

sprintf  formatted  output  conversion . 

sqrt  -  exponentiid,  logarithm,  power,  square  root.  *  •  • 

square  root,  exp,  log . 

sraud  -  random  number  generator . .  •  »  « 

srandom,  initstite,  setstate  -  better  random . 

If cani  -  formatted  input  conversion.  •  . . 

St  *-  Driver  for  Sysgen  SC  4000  (Archive)  Tape . 

ST-&03  Disk  Controllers.  .  . . 

stack . . . 

stack.  ♦  . 

stack  context,  * . 

stand  alone  memory  test . 

stand  alone  test  for  the  Sun  video  graphics  board.  •  •  * 

stand-alone  utility  package . 

standard  buffered  iupnt/outpnt  package . 

standard  format  host  tables . . 

standard  output  to  many  files . . . 

stat,  Istat,  fstat  -  get  file  status.  «  «  «  . . 

state . 

state . 

state  with  that  on  disk . . 

statement.  . . 

static  information  about  the  file83r8tems, 

statistics.  . . . . 

statistics. 

statistics . . . .  «  • 

statistics . 

status . 

status . * . 

status . 

status . . 

status  inquiries . 

status  of  local  machines . 

status  server . . . . 

stdio  -  standard  buffered  input/output  package . 

sticky  -  executable  files  with  persistent  text. 

stop . 

stop:  halt  a  job  or  process . .  « 

stop  the  processor . 

stop  until  signal . .  •  «  •  * 

storage  consistency  check . 

store,  delete,  first  key,  next  key  -  data  base . 

streat,  strncat,  stremp,  stmemp,  strepy,  stmepy,  «  .  •  « 

stremp,  stmemp,  strepy,  stmepy,  strlen,  index,  .  •  .  . 

strepy,  stmepy,  strlen,  index,  rindex  -  string  . 

stream . . . 

stream . . . .  .  •  . 

stream . . . .  ♦ 

stream,  getc,  getchar . 

stream . 

stream,  putc,  . 

stream . .  «  «  •  * 

stream,  setbuf,  *  «  * . •  «  •  « 

stream . * . . 

stream  editor  . 

stream  status  inquiries . . . 

stream  to  a  remote  command,  remd,  . 

stream  to  a  remote  command . 

Streaming  Tape  Drive . 

string  from  a  stream.  . . 

string  on  a  stream . . 

string  operations.  . . * . . 


alarm(3F) 

8wapon(8) 

spelifll 

epell(l) 

spetl(l) 

8pcn(l) 

8pline(lG) 

split(l) 

8plit(l) 

fsplit(l) 

frexp(3) 

uuclean(8C) 

Ipnn(l) 

printf(3S) 

exp(3M) 

exp(3M) 

rand(3Cl 

randomfs) 

scanf(3S) 

st(4S) 

8d(4S) 


csh(l) 

C8h(l) 

sigstack(2) 

imemte8t(88) 

gxtest(88) 

diag(8s) 

intro(3S) 

htable(8) 

tee(l) 

8tat(2) 

reset(l) 

8tty(3C) 

f8ync(2) 

C8h(l) 

fstab(5) 

C8h(l) 

iostat  (8) 

peifmon(l) 

vinstat(8) 

exit(3F) 

netstat(8) 

ps(l) 

8tat(2) 

ferTor(3S) 

niptime(lC) 

rwhod(80) 

intro(3S) 

stick^S) 

wait(2) 

csh(l) 

halt(8) 

pause(3C) 

icheck(8) 

dbm(3X) 

8tring(3) 

Btring(3) 

Btring(3) 

fclo8e(3S) 

fopen(3S) 

f8eek(3S) 

getc(3S) 

gCt8(SS) 

putc(3S) 

put8(3S) 

8etbuf(dS) 

ungetc(3S) 

8ed(l) 

feiTor(3S) 

rcmd(3N) 

rexec{3N) 

ar(4S) 

get8(3S) 

put8(3S) 

bstring(3) 
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strncmp,  strcpy,  etracpy^  etrica,  index,  rindex  - 
extrnci  etrinf^a  from  C  progmua  to  implement  ah&red 

other  binary,  file, 
rtringa,  xstr  -  extract 
atringa  -  find  printable 

baaename  - 

aircat,  atmeat,  atremp,  atmemp,  atrepy,  atmepy, 
index,  rindex  -  airing  operations,  atreat, 
airing  operations,  atreat,  atmeat,  atremp, 
atreat,  atmeat,  atremp,  atmemp,  atrepy. 


inewa  - 
poatnewa  - 
alarm  -  execute  a 
atom,  delete,  firatkey,  nextkey  -  data  base 

an  • 

aces  -  front  end  for  the  .SM  SCCS 

anm  - 
dn  - 
qnot  - 

en  - 
bw  - 

colordemoB  -  demonstrate 
eg- 

cona  ~  driver  for 
baunenbe  -  view  3-D 
bdemoB  -  demonstrate 
mouse  - 

gxtest  -  stand  alone  teat  for  the 
win  - 

aun  -  IB  current  machine  a 

auntoola  -  the 
s3me  -  update  the 
sync  -  update  the 
update  -  periodically  update  the 
sync  -  update 
suspend:  suspend  a  shell,  resuming  its 
intro  -  introduction  to  special  files  and  hardware 

routing  -  ayatem 
auapend: 
sleep  - 
sleep  - 
sleep  - 


swab  - 
swapon  -  add  a 
paging/swapping. 
swapping. 

swapon  -  add  a  swap  device  for Jnterieaved  paging/ 
swapon  -  specify  additional  device  for  paging  and 

breaksw:  exit  from 
case:  selector  in 
default:  catchall  clause  in 
>  endsw:  terminate 

readlink  -  read  value  of  a 
symiink  -  make 
strip  -  remove 

link, 


disk,  faync- 
aclcct  - 

cah  -  a  shell  (command  interpreter)  with  C-like 

measages.  perror, 
at  -  Driver  for 


string  operations,  atreat,  atmeat,  atremp,  •  .  . 

at  rings,  xatr  - . 

strings  -  find  printable  airings  in  an  object,  or 
airings  from  C  programs  to  implement  shared 
airings  in  an  object,  or  other  binary,  file.  ♦  ♦  « 
atrip  remove  symbols  and  relocation  bits.  •  . 

atrip  filename  affixes.  . . 

atrlen,  index,  rindex  -  string  operations . 

atmeat,  atremp,  atrnemp,  atrepy,  stmepy,  strien, 
atmemp,  atrepy,  atrnepy,  at  Hen,  index,  rindex  ~ 
atmepy,  atrlen,  index,  rindex  -  string/  •  -  .  « 

atty  -  set  terminal  options . 

atty,  gtiy  -  set  and  get  terminal  atate . 

au  -  aubatitute  user  id  temporarily . 

submit  news  articles . 

submit  news  aitictes.  •  *  * . 

subroutine  after  a  specified  time . 

subroutines,  dbminit,  fetch . . 

substitute  user  id  temporarily . 

subsystem.  . . 

sum  -  sum  and  count  blocks  in  a  file . 

sum  and  count  blocks  in  a  file . * 

summarise  disk  usage.  •  •  ; . .  .  • 

summarise  file  system  ownership . 

aun  -  is  current  machine  a  aun  workstation.  «  • 
Sun  5  Mb/s  experimental  Ethernet  interface. 

Sun  black  and  white  frame  buffer  . 

Sun  Color  Graphics  Display. . 

Sun  color  grapbica  interface . 

Sun  conaote . 

Sun  logo . . 

Sun  Monochrome  Bitmap  Display.  ...... 

Sun  mouse . 

Sun  video  graphics  board . 

Sun  window  system . 

sun  workstation . . . 

Buntools  -  the  Suntools  window  environment. 

Suntools  window  environment . 

super  block . 

super  block . 

super  block . . . 

fuper-^block . 

superior.  . 

support . . . .  .  .  . 

supporting  for  local  network  packet  routing.  .  . 

suspend  a  sbcll,  resuming  its  superior . 

suspend  execution  for  an  interval . 

suspend  execution  for  an  interval . 

suspend  execution  for  interval. 

suspend:  suspend  a  shell,  resuming  its  superior. 

swab  -  swap  bytes . 

swap  bytes . 

swap  device  for  iutetieaved  paging/swapping. 
swapon  -  add  a  swap  device  for  interleaved  •  » 
swapon  -  specify  additional  device  for  paging  and 

swapping.  «  •  •  . . . 

swapping . 

switch . * . 

switch . 

switch . . . 

switch . 

switch:  mniti-way  command  branch . 

symbolic  link. 

symbolic  link  to  a  file . 

symbols  and  relocation  bits.  «  •  . . 

symtink  -  make  symbolic  link  to  a  file . 

aymlnk  -  make  a  link  to  an  existing  file.  .  .  » 

sync  -  update  super-block.  . . 
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Revised  for  Sun  Release  1*1,  April  1984 

This  document  summarizes  the  facilities  provided  by  the  LI  and  later  releases  of  the  UNDCf 
operating  system  for  the  Sun  Workstation,  It  does  not  attempt  to  act  as  a  tutorial  for  use  of 
the  system  nor  does  it  attempt  to  explain  or  justify  the  design  of  the  system  facilities.  It  gives 
neither  motivation  nor  implementation  details,  in  favor  of  brevity.  This  document  is  in  three 
major  parts: 

Part  I  describes  the  basic  kernel  functions  provided  to  a  UNIX  process:  process  naming  and 
protection,  memory  management,  8oft'i?are  interrupts,  object  references  (descriptors), 
time  and  statistics  functions,  and  resource  controls.  These  facilities,  as  well  as  facilities 
for  bootstrap,  shutdown  and  process  accounting,  are  provided  solely  by  the  kernel. 

Part  II  describes  the  standard  system  abstractions  for  files  and  file  systems,  communication, 
terminal  handling,  and  process  control  and  debugging.  These  facilities  are  imple¬ 
mented  by  the  operating  system  or  by  network  server  processes. 

Part  III  is  an  appendix  containing  a  summary  of  the  facilities  described  in  parts  I  and  11, 

Q 


Notation  and  Types 

The  notation  used  to  describe  system  calls  is  a  variant  of  a  C  language  call,  consisting  of  a  pro¬ 
totype  call  followed  by  declaration  of  parameters  and  results.  An  additional  keyword  result, 
not  part  of  the  normal  C  language,  is  used  to  indicate  which  of  the  declared  entities  receive 
results.  As  an  example,  consider  the  read  call,  as  described  in  section  8.1: 

cc  “  read(fd,  buf,  nbytes); 

result  int  cc;  int  fd;  result  char  ♦buf;  int  nbytes; 

The  first  line  shows  how  the  read  routine  is  called,  with  three  parameters.  As  shown  on  the 
second  line  cc  is  an  integer  and  read  also  returns  information  in  the  parameter  buf. 

Description  of  all  error  conditions  arising  from  each  system  call  is  not  provided  here;  they 
appear  in  the  System  Interface  Manual.  In  particular,  when  accessed  from  the  C  language, 
many  calls  return  a  characteristic  -1  value  when  an  error  occurs,  returning  the  error  code  in  the 
global  variable  errno.  Other  languages  may  present  errors  in  different  ways, 

A  number  of  system  standard  types  are  defined  in  the  <sys/types.h>  include  file  and  used  in 
the  specifications  here  and  in  many  C  programs.  These  include  caddr^t  giving  a  memory 
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address  (typically  as  a  character  pointer),  off_t  giving  a  file  o£bet  (typically  as  a  long  integer), 
and  a  set  of  unsigned  types  u_char,  ujshort,  u_int  and  u_long,  shorthand  names  for 
unsigned  char,  unsigned  short,  etc. 
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Part  I  —  Kernel  Primitives 


The  facilities  available  to  a  UNIX  user  process  are  logically  divided  into  two  parts:  kernel  facili¬ 
ties  directly  implemented  by  UNIX  code  running  in  the  operating  system,  and  system  facilities 
implemented  either  by  the  system,  or  in  cooperation  with  a  server  process.  The  kernel  facilities 
are  described  in  this  part  of  the  document. 

The  facilities  implemented  in  the  kernel  are  those  which  define  the  UNIX  virtual  machme  which 
each  process  rans  in.  Like  many  real  machines,  this  virtual  machine  has  memory  management 
hardware,  an  interrupt  facility,  timers  and  counters.  The  UNIX  virtual  machine  also  allows 
access  to  files  and  other  objects  through  a  set  of  descriptors.  E3u;h  descriptor  resembles  a  device 
controller,  and  supports  a  set  of  operations.  Like  devices  on  real  machines,  some  of  which  are 
internal  to  the  machine  and  some  of  which  are  external,  parts  of  the  descriptor  machinery  are 
built-in  to  the  operating  system,  while  other  parts  we  often  implemented  in  server  processes  on 
other  machines.  The  facilities  provided  through  the  descriptor  machinery  are  described  in  Part 
II. 
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1.  Processes  and  Protection 


1.1.  Host  and  Process  Identifiers 

Each  UNIX  host  has  associated  with  it  a  32-bit  host  id,  and  a  host  name  of  up  to  255  characters. 
These  are  set  (by  a  privileged  user)  and  returned  by  the  calls: 

sethostid(ho8tid); 
long  hostid; 

hostid  =  gethostidO; 
result  long  hostid; 

8ethostname(name,  len); 
char  *name;  int  len; 

gethostname(buf,  buflen); 
result  char  *buf;  int  buflen; 

The  host  id  is  not  used  in  this  release  of  the  system.  The  buf  containing  the  host  name  returned 
by  gethottname  is  null-terminated  (if  space  allows). 

On  each  host  runs  a  set  of  proectses.  Each  process  is  largely  independent  of  other  processes, 
having  its  own  protection  domain,  address  space,  timers,  and  an  independent  set  of  references  to 
system  or  user  implemented  objects. 

Each  process  in  a  host  is  named  by  an  integer  called  the  procctf  id.  This  number  is  in  the  range 
1-30000  and  is  returned  by  the  getpid  routine: 

pid  =“  getpidO; 
result  int  pid; 

On  each  UNIX  host  this  identifier  is  guaranteed  to  be  unique;  in  a  multi-host  environment,  the 
(hostid,  process  id)  pairs  are  guaranteed  unique. 


1.2.  Process  Creation  and  Termination 

A  new  process  is  created  by  making  a  logical  duplicate  of  an  existing  process: 

pid  =  forkQ; 
result  int  pid; 

The  fork  call  returns  twice,  once  in  the  parent  process,  where  pid  is  the  process  identifier  of  the 
child,  and  once  in  the  child  process  where  pid  is  0.  The  parent-child  relationship  induces  a 
hierarchical  structure  on  the  set  of  processes  in  the  system. 

A  process  may  terminate  by  executing  an  exit  call: 

exit(8tatus); 
int  status; 

returning  8  bits  of  exit  status  to  its  parent. 

When  a  child  process  exits  or  terminates  abnormally,  the  parent  process  receives  information 
about  any  event  which  caused  termination  of  the  child  process.  A  second  call  provides  a  non- 
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blocking  interface  and  may  also  be  used  to  retrieve  information  about  resources  consumed  by 
the  process  during  its  lifetime. 

^include  <sys/wait.h> 
pid  a  wait(astatus); 

result  int  pid;  result  union  wait  *astatus; 

pid  ~  wait3(a8tatu8,  options^  arusage); 
result  int  pid;  result  union  waitstatus  ^astatus; 
ipt  options;  result  struct  rusage  ♦arusage; 

A  process  can  overlay  itself  with  the  memory  image  of  another  process,  passing  the  newly 
created  process  a  set  of  parameters,  using  the  call: 

execve(name,  argv,  envp) 
char  ♦name,  ♦♦argv,  ♦♦envp; 

The  specified  name  must  be  a  file  which  is  in  a  format  recognized  by  the  system,  either  a  binary 
executable  file  or  a  file  which  causes  the  execution  of  a  specified  interpreter  program  to  process 
its  contents. 


1.3.  User  and  Group  Ids 

Each  process  in  the  system  has  associated  with  it  two  user-id’s:  a  real  user  id  and  a  effective 
user  id,  both  non-negative  16  bit  integers.  Each  process  has  an  real  accounting  group  id  and  an 
effective  accounting  group  id  and  a  set  of  aceeso  group  id’s.  The  group  id’s  are  non-negative  16 
bit  integers.  Each  process  may  be  in  several  different  access  groups,  with  the  maximum  con¬ 
current  number  of  access  groups  a  system  compilation  parameter,  the  constant  NGROUPS  in 
the  file  <8y8/param.h>,  guaranteed  to  be  at  least  8. 

The  real  and  effective  user  ids  associated  with  a  process  are  returned  by: 

ruid  s  getuid(); 
result  int  ruid; 

euid  »  geteuidO; 
result  int  euid; 

the  real  and  effective  accounting  group  ids  by: 

rgid  =»  getgidO; 
result  int  rgid; 

egid  =»  getegid(); 
result  int  egid; 

and  the  access  group  id  set  is  returned  by  a  getgroups  call: 

ngroups  =■  getgroups(gidset8ize,  gidset); 

result  int  ngroups;  int  gidsetsize;  result  int  gidset[gidsetsize]; 

The  user  and  group  id's  are  assigned  at  login  time  using  the  setreuid,  setregid,  and  setgroups 
calls: 
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8etreaid(ruid,  euid); 
ii^f;  mid,  euid; 

8etregid(rgid,  egid); 
int  rgid,  egid; 

setgroups(gidsetsize,  gidset); 
int  gidsetsize;  int  gidset  [gidsetsize]; 

The  tetrevid  call  sets  both  the  real  and  effective  user-id’s,  while  the  setrcgid  call  sets  both  the 
rcjd  and  effective  accounting  group  id’s.  Unless  the  caller  is  the  super-user,  ftifrf  must  be  equal 
to  either  the  current  real  or  effective  user-id,  and  rgid  equal  to  either  the  current  real  or  effective 
accounting  group  id.  The  aetgroup*  call  is  restricted  to  the  super-user. 

1,4.  Process  Groups  and  System  Terminals 

Each  process  in  the  system  is  also  normally  associated  with  a  process  group.  The  group  of 
processes  in  a  process  group  is  sometimes  referred  to  as  a  Job  and  manipulated  by  high-level  sys¬ 
tem  software  (such  as  the  shell)*  The  current  process  group  of  a  process  is  returned  by  the 
getpgrp  call: 

Pgrp  “  getpgrp(pid); 
result  int  pgrp;  int  pid; 

The  process  group  associated  with  a  process  may  be  changed  by  the  tetpgrp  call: 

setpgrp(pid,  pgrp); 
int  pid,  pgrp; 

Newly  created  processes  are  assigned  process  id’s  distinct  from  all  processes  and  process  groups, 
and  the  same  process  group  as  their  parent.  A  normal  (unprivileged)  process  may  set  its  process 
group  equal  to  its  process  id.  A  privileged  process  may  set  the  process  group  of  any  process  to 
any  value. 

When  a  process  is  in  a  specific  process  group  it  may  receive  software  interrupts  affecting  the 
group,  causing  the  group  to  suspend  or  resume  execution  or  to  be  interrupted  or  terminated.  In 
particular,  every  system  terminal  has  a  process  group  and  only  processes  which  are  in  the  pro¬ 
cess  group  of  a  terminal  may  read  from  the  terminal,  allowing  arbitration  of  terminals  among 
several  different  jobs.  A  process  can  examine  the  process  group  of  a  terminal  via  the  ioetl  call: 

ioctl(fd,  TIOCGPGRP,  pgrp); 
int  fd;  result  int  *pgrp; 

A  process  may  change  the  process  group  of  any  terminal  which  it  can  write  by  the  ioetl  call: 

ioctl(fd,  TIOeSPGRP,  pgrp); 
int  fd;  int  *pgrp; 

The  terminal’s  process  group  may  be  set  to  any  value.  Thus,  more  than  one  terminal  may  be  in 
a  process  group. 

Each  process  in  the  system  is  usually  associated  with  a  control  ter  mined,  accessible  through  the 
file  /dev/tty.  A  newly  created  process  inherits  the  control  terminal  of  its  parent.  A  process 
may  be  in  a  different  process  group  than  its  control  terminal,  in  which  case  the  process  does  not 
receive  software  interrupts  affecting  the  control  terminal’s  process  group. 
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2.  Memory  management 

This  section  represents  the  interface  planned  for  later  releases  of  the  system.  Of  the  calls 
described  in  this  section,  only  »brk,  etpagetize,  and  mmap  are  included  in  the  current  release. 
Note  that  mmap  is  restricted  in  that  it  only  works  with  certain  character  devices  such  as  the 
framebuffer  and  devices  like  mbmem. 

2.1.  Data,  and  Stack 

Each  propess  begins  execution  with  three  logical  areas  of  memory  called  text,  data  and  stack. 
The  text  area  is  read-only  and  shared,  while  the  data  and  stack  areas  are  private  to  the  process. 
Both  the  data  and  stack  areas  may  be  extended  and  contracted  on  program  request.  The  call 

addr  »=  sbrk(incr); 
result  caddrjt  addr;  int  incr; 

changes  the  size  of  the  data  area  by  iner  bytes  and  returns  the  new  end  of  the  data  area,  while 

addr  =■  sstk(incr); 

result  caddrjt  addr;  int  incr; 

changes  the  size  of  the  stack  area.  The  stack  area  is  also  automatically  extended  as  needed. 
On  the  VAX  the  text  and  data  areas  are  adjacent  in  the  PO  region,  while  the  stack  section  is  in 
the  PI  region,  and  grows  downward. 

2.2.  Nfapping  Pages 

The  systfjn  supports  sharing  of  data  between  processes  by  allowing  pages  to  be  mapped  into 
memory. ;  These  mapped  pages  may  be  shared  with  other  processes  or  private  to  the  process. 
Protection  and  sharing  options  are  defined  in  <mman.h>  as: 

/*  protections  are  chosen  from  these  bits,  or-cd  together  */ 

#define  PROTJREAD  0x4  /*  pages  can  be  read  */ 

#define  PROT_WRITE  0x2  /*  pages  can  be  written  */ 

^define  PROT_EXEC  0x1  /♦  pages  can  be  executed  */ 

/*  sharing  types;  choose  either  SHARED  or  PRIVATE  ♦/ 
fl^define  MAP_SHARED  1  /*  share  changes  */ 

^define  MAP_PRIVATE  2  /♦  changes  are  private  */ 

The  cpu-(||{ppendent  size  of  a  page  is  returned  by  the  getpagesize  system  call: 

P^^gesize  =  getpagesize(); 
reiralt  int  pagesize; 

The  call: 

mmap(addr,  len,  prot,  share,  fd,  pos); 
caddrjt  addr;  int  len,  prot,  share,  fd;  offjt  pos; 

causes  the  pages  starting  at  addr  and  continuing  for  len  bytes  to  be  mapped  from  the  object 
represented  by  descriptor  fd,  at  absolute  position  pos.  The  peu'ameter  share  specifies  whether 
modifications  made  to  this  mapped  copy  of  the  page,  are  to  be  kept  private,  or  are  to  be  shared 
with  other  references.  The  parameter  prot  specifies  the  accessibility  of  the  mapped  pages.  The 
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addfy  leriy  and  pos  parameters  must  all  be  multiples  of  the  pagesize. 

A  process  can  move  pages  within  its  own  memory  by  using  the  mremap  call: 

mremap(addr^  len^  prot,  share^  fromaddr); 
caddr_t  addr;  int  Icn,  prot>  share;  caddrjt  fromaddr; 

This  call  maps  the  pages  starting  at  fromaddr  to  the  address  specified  by  addr, 

A  mapping  can  be  removed  by  the  call 

ii\finmap(addr^  len); 
c|^dr_t  addr;  int  len; 

This  causes  further  references  to  these  pages  to  refer  to  private  pages  initialized  to  zero. 

2.3.  Page  Protection  Control 

A  process  can  control  the  protection  of  pages  using  the  call 

mprotect(addr^  len,  prot); 
caddr_t  addr;  int  len,  prot; 

This  call  changes  the  specified  pages  to  have  protection  prot. 


2.4.  Giving  and  Getting  Advice 


A  process  that  has  knowledge  of  its  memory  behavior  may  use  the  madvise  call: 

madvise(addr,  len,  behav); 
caddrjt  addr;  int  len,  behav; 


Behav  describes  expected  behavior,  as  given  in  <mman.h>: 

#define  MADV_NORMAL  0  /*  no  further  special  treatment  */ 

#define  MADV JRANDOM  1  /•  expect  random  page  references  */ 

#define  MADV_SEQUENTIAL  2/*  expect  sequential  references  */ 

^define  MADV_WILLNEED  3  /*  will  need  these  pages  */ 

#define  MADV_J)ONTNEED  4  /♦  don’t  need  these  pages  */ 

Finally,  a  process  may  obtain  information  about  whether  pages  are  core  resident  by  using  the 
call 


mincore(addr,  len,  vec); 

caddrjt  addr;  int  len;  result  char  *vec; 

Here  the  current  core  residency  of  the  pages  is  returned  in  the  character  array  tree,  with  a  value 
of  1  meaning  that  the  page  is  in-core. 
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3.  Signals 

The  system  defines  a  set  of  signalt  that  may  be  delivered  to  a  process.  Signal  delivery  resembles 
the  occurrence  of  a  hardware  interrupt:  the  signal  is  blocked  from  further  occiirrence,  the 
current  process  context  is  saved,  and  a  new  one  is  built.  A  process  may  specify  the  handler  to 
which  a  signal  is  delivered,  or  specify  that  the  signal  is  to  be  blocked  or  ignored.  A  process  may 
also  spepfy  that  a  default  action  is  to  be  taken  when  signals  occur. 

Some  silpals  will  cause  a  process  to  exit  when  they  are  not  caught.  This  may  be  accompanied 
by  creaf^lon  of  a  core  image  file,  containing  the  current  memory  image  of  the  process  for  use  in 
post-mortem  debugging.  A  process  may  choose  to  have  signals  delivered  on  a  special  stack,  so 
that  sophisticated  software  stack  manipulations  are  possible. 

All  signals  have  the  same  priority.  If  multiple  signals  are  pending  simultaneously,  the  order  in 
which  they  are  delivered  to  a  process  is  implementation  specific.  Signal  routines  execute  with 
the  signal  that  caused  their  invocation  blocked,  but  other  signals  may  yet  occur.  Mechanisms 
are  provided  whereby  critical  sections  of  code  may  protect  themselves  against  the  occurrence  of 
specified  signals. 

3.1.  Signal  Types 

The  signals  defined  by  the  system  fall  into  one  of  five  classes:  hardware  conditions,  software 
conditions,  input/output  notification,  process  control,  or  resource  control.  The  set  of  signals  is 
defined  in  the  file  <signal.h>. 

Hardware  signals  are  derived  from  exceptional  conditions  which  may  occur  during  execution. 
Such  signals  include  SIGFPE  representing  floating  point  and  other  arithmetic  exceptions, 
SIGILL  for  illegal  instruction  execution,  SIGSEGV  for  addresses  outside  the  currently  assigned 
area  of  memory,  and  SIGBUS  for  accesses  that  violate  memory  protection  constraints.  Other, 
more  cpu-specific  hardware  signals  exist,  such  as  those  for  the  various  customer-reserved 
instructions  on  the  VAX  (SIGIOT,  SIGEMT,  and  SIGTRAP). 

Software  signals  reflect  interimpts  generated  by  user  request:  SIGINT  for  the  normal  interrupt 
signal;  SIGQUIT  for  the  more  powerful  quit  signal,  that  normally  causes  a  core  image  to  be  gen¬ 
erated;  SIGHUP  and  SIGTERM  that  cause  graceful  process  termination,  either  because  a  user 
has  “hung  up”,  or  by  user  or  program  request;  and  SIGKILL,  a  more  powerful  termination  sig¬ 
nal  which  a  process  cannot  catch  or  ignore.  Other  software  signals  (SIGALRM,  SIGVTALRM, 
SIGPROF)  indicate  the  expiration  of  interval  timers. 

A  process  can  request  notification  via  a  SIGIO  signal  when  input  or  output  is  possible  on  a 
descriptor,  or  when  a  non-blocking  operation  completes.  A  process  may  request  to  receive  a 
SIGURG  signal  when  an  urgent  condition  arises. 

A  process  may  be  ttopped  by  a  signal  sent  to  it  or  the  members  of  its  process  group.  The  SIG- 
STOP  signal  is  a  powerful  stop  signal,  because  it  cannot  be  caught.  Other  stop  signals 
SIGTSTP,  SIGTTIN,  and  SIGTTOU  are  used  when  a  user  request,  input  request,  or  output 
request  respectively  is  the  re^on  the  process  is  being  stopped.  A  SIGCONT  signal  is  sent  to  a 
process  when  it  is  continued  from  a  stopped  state.  Processes  may  receive  notification  with  a 
SIGCHLD  signal  when  a  child  process  changes  state,  either  by  stopping  or  by  terminating. 

Exceeding  resource  limits  may  cause  signals  to  be  generated.  SIGXCPU  occurs  when  a  process 
nears  its  CPU  time  limit  and  SIGXFSZ  warns  that  the  limit  on  file  size  creation  has  been 
reached. 
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3.2.  Signal  Handlers 

A  process  has  3  handler  associated  with  each  signal  that  controls  the  way  the  signal  is  delivered* 
The  call 


^include  <signal.h> 

struct  sigvec  { 

int 

(♦8V_handlcrX); 

Int 

8V_mask; 

int 

sv.onstack; 

); 

8igvec(8igno,  sv,  osv) 

int  signo;  struct  sigvec  *sv;  result  struct  sigvec  ♦osv; 

assigns  interrupt  handler  address  svjhtindkr  to  signal  $igno.  Each  handler  address  specifies 
either  an  interrupt  routine  for  the  signal,  that  the  signal  is  to  be  ignored,  or  that  a  default 
action  (usually  process  termination)  is  to  occur  if  the  signal  occurs.  The  constants  SIG  JGN 
and  SIG  J>EF  used  as  values  for  svjhandlcr  cause  ignoring  or  defaulting  of  a  condition.  The 
4Vjina$k  and  sv_onstack  values  specify  the  signal  mask  to  be  used  when  the  handler  is  invoked 
and  whether  the  handler  should  operate  on  the  normal  run-time  stack  or  a  special  signal  stack 
(see  below).  If  osv  is  non-tero,  the  previous  signal  vector  is  returned. 

When  a  signal  condition  arises  for  a  process,  the  signal  is  added  to  a  set  of  signals  pending  for 
the  process.  If  the  signal  is  not  currently  blocked  by  the  process  then  it  will  be  delivered.  The 
process  of  signal  delivery  adds  the  signal  to  be  delivered  and  those  signals  specified  in  the  associ¬ 
ated  signal  handler's  svjtnask  to  a  set  of  those  masked  for  the  process,  saves  the  current  process 
context,  and  places  the  process  in  the  context  of  the  signal  handling  routine.  The  call  is 
arranged  so  that  if  the  signal  handling  routine  exits  normally  the  signal  mask  will  be  restored 
and  the  process  will  resume  execution  in  the  original  context.  If  the  process  wishes  to  resume  in 
a  different  context,  then  it  must  arrange  to  restore  the  signal  mask  itself. 

The  mask  of  blocked  signals  is  independent  of  handlers  for  signals.  It  prevents  signals  from 
being  delivered  much  as  a  raised  hardware  interrupt  priority  level  prevents  hardware  interrupts. 
Preventing  an  interrupt  from  occurring  by  changing  the  handler  is  analogous  to  disabling  a  dev¬ 
ice  from  further  interrupts. 

The  signal  handling  routine  svjkandler  is  called  by  a  C  call  of  the  form 

(♦svJiandlerXsiffno,  code,  sep); 

int  signo;  long  code;  struct  sigeontext  ♦sep; 

The  signo  gives  the  number  of  the  signal  that  occurred,  and  the  codcf  a  word  of  information 
supplied  by  the  hardware.  The  sep  parameter  is  a  pointer  to  a  machine-dependent  structure 
containing  the  information  for  restoring  the  context  before  the  signal. 

3.3.  Sending  Signals 

A  process  can  send  a  signal  to  another  process  or  group  of  processes  with  the  calls: 
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kill(pid,  signo); 
int  pid,  signo; 

kilIpgTp(pgrp,  signo); 
int  pgrp,  signo; 

Unless  the  process  sending  the  signal  is  privileged,  it  and  the  process  receiving  the  signal  must 
have  the  same  effective  user  id. 

Signals  are  also  sent  implicitly  from  a  terminal  device  to  the  process  group  associated  with  the 
terminal  when  certain  input  characters  are  typed. 


3.4*  Protecting  Critical  Sections 

To  block  a  section  of  code  against  one  or  more  signals,  a  tigblock  call  may  be  used  to  add  a  set 
of  signals  to  the  existing  mask,  returning  the  old  mask; 

oldraask  »  sigblock(mask); 
result  long  oldmask;  long  mask; 

The  old  mask  can  then  be  restored  later  with  sigaetmatk, 

oldmask  sig3etmask(ma3k); 
result  long  oldmask;  long  mask; 

The  tigblock  call  can  be  used  to  read  the  current  mask  by  specifying  an  empty  maak. 

It  is  possible  to  check  conditions  with  some  signals  blocked,  and  then  to  pause  waiting  for  a  sig¬ 
nal  and  restoring  the  mask,  by  using: 

sigpause(ma8k); 
long  mask; 


3.6.  Signal  Stacks 

Applications  that  maintmn  complex  or  fixed  site  stacks  can  use  the  call 

struct  sigstack  { 

caddrjt  ss_sp; 
int  ss_onstack; 

}; 

sigstack(ss,  oss) 

struct  sigstack  ^ss;  result  struct  sigstack  «oss; 

to  provide  the  system  with  a  stack  based  at  aa_tp  for  delivery  of  signals.  The  value  ta_onatack 
indicates  whether  the  process  is  currently  on  the  signal  stack,  a  notion  maintained  in  software 
by  the  system. 

When  a  signal  is  to  be  delivered,  the  system  checks  whether  the  process  is  on  a  signal  stack.  If 
not,  then  the  process  is  switched  to  the  signal  stack  for  delivery,  with  the  return  from  the  signal 
arranged  to  restore  the  previous  stack. 

If  the  process  wishes  to  take  a  non-local  exit  from  the  signal  routine,  or  run  code  from  the  signal 
stack  that  uses  a  different  stack,  a  aigatack  call  should  be  used  to  reset  the  signal  stack. 
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4.1  •  Real  Time 

The  system ^8  notion  of  the  current  Greenwich  time  and  the  current  time  zone  is  set  and 
returned  by  the  calls: 

^include  <sys/time.h> 

8ettimeofday(tvp^  tzp); 
struct  timeval  *tp; 
struct  timezone  *tzp; 


gettimeofday(tp,  tzp); 
result  struct  timeval  ‘^tp; 
result  struct  timezone  *tzp; 

where  the  structures  are  defined  in  <$y$l timc,h>  as: 

struct  timeval  ( 

long  tv_sec;  /♦  seconds  since  Jan  1,  1070  ♦/ 

long  tv^usec;  /♦  and  microseconds  */ 

}; 


struct  timezone  { 

int  tz^minutesurest;  /♦  of  Greenwich  */ 

int  tz_dsttime;  /*  type  of  dst  correction  to  apply  ♦/ 

}; 

Earlier  versions  of  UNIX  contained  only  a  l-second  resolution  version  of  this  call,  which  remains 
as  a  library  routine: 

time(tvp) 
result  long  *tvp; 

or 


tv  "  time(O); 
result  long  tv; 

returning  only  the  tvjiec  field  from  the  gcttimeofday  call. 


4.2.  Interval  Time 

The  system  provides  each  process  with  three  interval  timers,  defined  in  <s3rs/time.h>: 

^define  ITIMER_REAL  0  /♦  real  time  intervals  ♦/ 

^define  ITIMER_VIRTUAL  1  /*  virtual  time  intervals  ♦/ 

^define  ITIMER_PROF  2  /*  user  and  system  virtual  time  */ 

The  ITIMER_REAL  timer  decrements  in  real  time.  It  could  be  used  by  a  library  routine  to 
maintain  a  wakeup  service  queue.  A  SIGALRM  signal  is  delivered  when  this  timer  expires. 
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The  ITIMER_yiRTUAL  timer  decrements  in  process  virtual  time.  It  runs  only  when  the  pro¬ 
cess  is  executing.  A  SIGVTALRM  signal  is  delivered  when  it  expires. 

The  ITIMER_PROF  timer,  decrements  both  in  process  virtual  time  and  when  the  system  is  run¬ 
ning  on  behalf  of  the  process.  It  is  designed  to  be  used  by  processes  to  statistically  profile  their 
execution.  A  SIGPROP  signal  is  delivered  when  it  expires. 

A  timer  value  is  defined  by  the  itimcrvat  structure: 

struct  itimerval  { 

struct  timeval  itjnterval;  /♦  timer  interval  ♦/ 

struct  timeval  it_valuc;  /♦  current  value  */ 

}; 

and  a  tinier  is  set  or  read  by  the  call: 

getitimer(irhich,  yalue); 

int  which;  result  struct  itimerval  *value; 

8etitimer(which,  value,  ovalue); 

int  which;  struct  itimerval  *  value;  result  struct  itimerval  *  ovalue; 

The  third  argument  to  tctitimer  specifies  an  optional  structure  to  receive  the  previous  contents 
of  the  interval  timer.  A  timer  can  be  disabled  by  specifying  a  timer  value  of  0. 

The  system  rounds  argument  timer  intervals  to  be  not  less  than  the  resolution  of  its  clock.  This 
clock  resolution  can  be  determined  by  loading  a  very  small  value  into  a  timer  and  reading  the 
timer  back  to  see  what  value  resulted. 

The  alarm  system  call  of  earlier  versions  of  UNIX  is  provided  as  a  library  routine  using  the 
1TIMER_11EAL  timer.  The  process  profiling  facilities  of  earlier  versions  of  UNIX  remain 
because  it  is  not  alwasrs  possible  to  guarantee  the  automatic  restart  of  system  calls  after  receipt 
of  a  signal. 

p^fil(buf,  bufsize,  ofiEset,  scale); 
result  char  *buf;  int  bufsize,  offset,  scale; 
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Each  process  has  access  to  resources  through  dcicrtptorM.  Each  descriptor  is  a  handle  allowing 
the  process  to  reference  objects  such  as  files^  devices  and  communications  links. 

5.1.  The  Reference  Table 

Rather  than  allowing  processes  direct  access  to  descriptors,  the  sjrstem  introduces  a  level  of 
indirection,  so  that  descriptors  may  be  shared  between  processes.  Each  process  has  a  descriptor 
reference  table,  containing  pointers  to  the  actual  descriptors.  The  descriptors  themselves  thus 
have  multiple  references,  and  are  reference  counted  by  the  system. 

Each  process  has  a  fixed  site  descriptor  reference  table,  where  the  site  is  returned  by  the  getdta- 
blesize  call: 

nds  =■  getdtablesite(); 
result  int  nds; 

and  guaranteed  to  be  at  least  as  large  as  the  constant  NOFILE  defined  in  <param.h>.  The 
entries  in  the  descriptor  reference  table  are  referred  to  by  small  integers;  for  example  if  there  are 
20  slots  they  are  numbered  0  to  10. 

5.2.  Descriptor  Properties 

Each  descriptor  has  a  logical  set  of  properties  maintained  by  the  system  and  defined  by  its  type. 
Each  type  supports  a  set  of  operations;  some  operations,  such  as  reading  and  writing,  are  com¬ 
mon  to  several  abstractions,  while  others  are  unique.  The  generic  operations  applying  to  many 
of  these  types  are  described  in  section  8.  Naming  contexts,  files  and  directories  are  described  in 
section  9.  Section  10  describes  communications  domains  and  sockets.  Terminals  and  (struc¬ 
tured  and  unstructured)  devices  are  described  in  section  11. 
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5.3.  Managing  Descriptor  References 

A  duplicate  of  a  descriptor  reference  may  be  made  by  doing 

n^w  =>  dup(old); 
result  int  new;  int  old; 

returning  a  copy  of  descriptor  reference  old  indistinguishable  from  the  original.  The  new  chosen 
by  the  system  will  be  the  smallest  unused  descriptor  reference  slot.  A  copy  of  a  descriptor  refeiv 
ence  may  be  made  in  a  specific  slot  by  doing 

dup2(otd,  new); 
int  old,  new; 

The  dupS  call  causes  the  system  to  deallocate  the  descriptor  reference  current  occupying  slot 
new,  if  any,  replacing  it  with  a  reference  to  the  same  descriptor  as  old.  This  deallocation  is  also 
performed  by: 

close(old); 
int  old; 
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5.4«  Multiplexing  Requests 

The  system  provides  a  standard  way  to  do  synchronous  and  asynchronous  multiplexing  of 
operations. 

Synchronous  multiplexing  is  performed  by  using  the  select  call: 

nds  8elect(nd,  in,  out,  except,  tvp); 
result  int  nds;  int  nd;  result  ♦in,  ♦out,  ♦except; 
struct  timeval  ♦tvp; 

The  select  call  examines  the  descriptors  specified  by  the  sets  m,  out  and  except,  replacing  the 
specified  bit  masks  by  the  subsets  that  select  for  input,  output,  and  exceptional  conditions 
respectively  {nd  indicates  the  size,  in  bits,  of  the  bit  masks).  If  any  descriptors  meet  the  follow¬ 
ing  criteria,  then  the  number  of  such  descriptors  is  returned  in  nds  and  the  bit  masks  are 
updated. 

•  A  descriptor  selects  for  input  if  an  input  oriented  operation  such  as  read  ot  receive  is  possi¬ 
ble,  or  if  a  connection  request  may  be  accepted  (see  section  10.1.4). 

•  A  descriptor  selects  for  output  if  an  output  oriented  operation  such  as  write  or  send  is  possi¬ 
ble,  or  if  an  operation  that  was  ^4n  progress’’,  such  as  connection  establishment,  has  com¬ 
pleted  (see  section  8.3). 

•  A  descriptor  selects  for  an  exceptional  condition  if  a  condition  that  would  cause  a  SIGURG 
signal  to  be  generated  exists  (see  section  3.1). 

If  none  of  the  specified  conditions  is  true,  the  operation  blocks  for  at  most  the  amount  of  time 
specified  by  tvp,  or  waits  for  one  of  the  conditions  to  arise  if  tvp  is  given  as  0. 

Options  affecting  i/o  on  a  descriptor  may  be  read  and  set  by  the  call: 

dopt  =  fcnt!(d,  cmd,  arg); 
result  int  dopt;  int  d,  cmd,  arg; 


/  ♦  interesting  values  for  cmd  ♦/ 


#define  F^SETFL  .  3 

#define  F_GETFL  4 

#define  F^SETOWN  5 

#define  F^GETOWN  6 


/♦  set  descriptor  options  */ 

/*  get  descriptor  options  */ 

/♦  set  descriptor  owner  (pid/pgrp)  ♦/ 
/♦  get  descriptor  owner  (pid/pgrp)  */ 


The  FJSETFL  cmd  may  be  used  to  set  a  descriptor  in  non-blocking  i/o  mode  and/or  enable  sig¬ 
nalling  when  i/o  is  possible.  F_SETOWN  may  be  used  to  specify  a  process  or  process  group  to 
be  signalled  when  using  the  latter  mode  of  operation. 

Operations  on  non-blocking  descriptors  will  either  complete  immediately,  note  an  error 
EWOULD BLOCK,  partially  complete  an  input  or  output  operation  returning  a  partial  count,  or 
return  an  error  EINPROGRESS  noting  that  the  requested  operation  is  in  progress.  A  descripn 
tor  which  has  signalling  enabled  will  cause  the  specified  process  and/or  process  group  be  sig¬ 
naled,  with  a  SIGIO  for  input,  output,  or  in-progress  operation  complete,  or  a  SIGURG  for 
exceptional  conditions. 

For  example,  when  writing  to  a  terminal  using  non-blocking  output,  the  system  will  accept  only 
as  much  data  as  there  is  buffer  space  for  and  return;  when  making  a  connection  on  a  socket,  the 
operation  may  return  indicating  that  the  connection  establishment  is  *in  progress”.  The  select 
facility  can  be  used  to  determine  when  further  output  is  possible  on  the  terminal,  or  when  the 
connection  establishment  attempt  is  complete. 
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6.  Resource  Controls 


6.1.  Process  Priorities 

The  system  gives  CPU  scheduling  priority  to  processes  that  have  not  used  CPU  time  recently. 
This  tends  to  favor  interactive  processes  and  processes  that  execute  only  for  short  periods.  It  is 
possible  to  determine  the  priority  currently  assigned  to  a  process,  process  group,  or  the  processes 
of  a  specified  user,  or  to  alter  this  priority  using  the  calls: 

#define  PRIO_PROCESS  0  /*  process  ♦/ 

^define  PRIO_PGRP  1  /*  process  group  •/ 

#define  PRIOJUSER  2  /*  user  id  */ 

prio  =  getpriol'lty(which,  who); 
result  int  prio;  int  which,  who; 

setpriority(which,  who,  prio); 
int  which,  who,  prio; 

The  value  prio  is  in  the  range  -20  to  20.  The  default  priority  is  0;  lower  priorities  cause  more 
favorable  execution.  The  getpriority  call  returns  the  highest  priority  (lowest  numerical  value) 
enjoyed  by  any  of  the  specified  processes.  The  setpriority  call  seta  the  priorities  of  all  of  the 
specified  processes  to  the  specified  value.  Only  the  super-user  may  lower  priorities. 


6.2.  Resource  Utilization 

The  resources  used  by  a  process  are  returned  by  a  getrutage  call,  returning  information  in  a 
structure  defined  in  <8ys/re80urce.h>: 

#define  RUSAGE_SELF  0  /*  usage  by  this  process  */ 

#define  RUSAGE.CHILDREN  -1/*  usage  by  all  children  */ 

getrusage(who,  rusage); 

int  who;  result  struct  rusage  *rusage; 

struct  rusage  { 


struct 

timevai  ru_utime;  /*  user  time  used  ♦/ 

struct 

timevai  ru.stime; 

/♦  system  time  used  */ 

int 

ru^maxrse; 

/*  maximum  core  resident  set  siee:  kbytes  */ 

int 

ru_ixrss; 

f*  integral  shared  memory  size  (kbytes^sec)  */ 

int 

ru_idrss; 

/•  unshared  data  ”  */ 

int 

ru_isrss; 

/*  unshared  stack  ”  ♦/ 

int 

ru_minflt; 

/♦  page-reclaims  */ 

int 

ru_majflt; 

/*  page  faults  ♦/ 

int 

ru_nswap; 

/♦  swaps  ♦/ 

int 

ru_inblockj 

/  ♦  block  input  operations  *  / 

int 

ru^oublock; 

/*  block  output  ”  */ 

int 

ru^msgsnd; 

/*  messages  sent  */ 

int 

ru_msgrcv; 

/*  messages  received  */ 

int 

ru_nsignals; 

f*  signals  received  */ 
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int  ru_jnvcsw;  /♦  voluntary  context  switches  */ 

int  ru_nivcsw;  /♦  involuntary  ”  */ 

}; 

The  who  parameter  specifies  whose  resource  usage  is  to  be  returned.  The  resources  used  by  the 
current  process,  or  by  all  the  terminated  children  of  the  current  process  may  be  requested. 

0.3.  Resource  Limits 

The  resources  of  a  process  for  which  limits  are  controlled  by  the  kernel  are  defined  in 
<87s/resource.h>,  and  controlled  by  the  getrlimit  and  setrlimit  calls: 

#define  RLIMITjCPU  0  /*  cpu  time  in  milliseconds  */ 

^define  RLIMIT_FSIZE  1  /*  maximum  file  size  */ 

^define  RLIMITJDATA  2  /*  maximum  data  segment  size  */ 

^define  RLIMITjSTACK  3  /*  maximum  stack  segment  size  */ 

#define  RLIMITjCORE  4  /*  maximum  core  file  size  *f 

^define  RLIMIT_JISS  S  /*  maximum  resident  set  size  */ 

#define  RLIM_NLIMITS  6 

#define  RLIMJNFINITY  0x7fffffff 

struct  rlimit  { 
int 
int 

}; 

getrIimit(resource,  rip); 

int  resource;  result  struct  rlimit  *rlp; 

setrlimit(resource,  rip); 

int  resource;  struct  rlimit  *rlp; 

Only  the  8uper*user  can  raise  the  maximum  limits.  Other  users  may  only  alter  rlim_cur  within 
the  range  from  0  to  rlimjmax  or  (irreversibly)  lower  rltmjmax. 


rlim_cur;  /*  current  (soft)  limit  ♦/ 

rlim_max;  f*  hard  limit  *f 
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7.  System  operation  support 

The  calls  in  this  section  are  permitted  only  to  a  privileged  user. 


7.1.  Bootstrap  Operations 

The  call 

mount(blkdeT,  dir,  ronly); 
cjiar  *blkdev,  *dip;  int  ronly; 

extends  the  UNIX  name  space.  The  mount  call  specifies  a  block  device  bUedev  containing  a  UNIX 
file  system  to  be  made  available  starting  at  dir.  If  ron/y  is  set  then  the  file  system  is  read-only; 
writes  to  the  file  system  will  not  be  permitted  and  access  times  will  not  be  updated  when  files 
are  referenced. 

The  call 

swapon(blkdev,  sise); 
char  ♦blkdev;  int  sise; 

specifies  a  device  to  be  made  available  for  paging  and  swapping. 


7 .2.  Shutdown  Operations 

The  call 

unmount(dir); 
char  ♦dir; 

unmounts  the  file  system  mounted  on  rfir.  This  call  will  succeed  only  If  the  file  system  is  not 
currently  being  used. 

The  call 

sync(); 

schedules  input/output  to  clean  all  system  buffer  caches. 

The  call 

reboot(how); 
int  how; 

causes  a  machine  halt  or  reboot.  The  call  may  request  a  reboot  by  specifying  how  as 
RB_AUTOBOOT,  or  that  the  machine  be  halted  with  RBJHALT.  These  constants  are  defined 
in  <sys/reboot.h>. 


7.3.  Accounting 

I 

The  system  optionally  keeps  an  accounting  record  in  a  file  for  each  process  that  exits  on  the 
system.  The  format  of  this  record  is  beyond  the  scope  of  this  document.  The  accounting  may 
be  enabled  to  a  file  name  by  doing 
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acct(path); 
char  *path; 

If  path  is  null,  then  accounting  is  disabled.  Otherwise,  the  named  file  becomes  the  accounting 
file. 


o 
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Part  n  —  System  Facilities 


This  part  of  the  document  discusses  the  system  facilities  that  are  not  considered  part  of  the  ker¬ 
nel. 

The  system  abstractions  described  are: 

Difcctoru  Contexts 

A  directory  context  is  a  position  in  the  UNIX  file  system  name  space.  Operations  on  files 
and  lather  named  objects  in  a  file  system  are  always  specified  relative  to  such  a  context. 

Files 

Files  are  used  to  store  uninterpreted  sequence  of  bytes  on  which  random  access  reads  and 
writes  may  occur.  Pages  from  files  or  devices  may  also  be  mapped  into  process  address 
space.  A  directory  may  be  read  as  a  filef- 

Communications  Domains 

A  communications  domain  represents  an  interprocess  communications  environment,  such  as 
the  communications  facilities  of  the  UNIX  system,  communications  in  the  INTERNET,  or  the 
resource  sharing  protocols  and  access  rights  of  a  resource  sharing  system  on  a  local  network. 

Sockets 

A  soc)cet  is  an  endpoint  of  communication  and  the  focal  point  for  IPC  in  a  communications 
domain.  Sockets  may  be  created  in  pairs,  or  given  names  and  used  to  rendezvous  with 
other  sockets  in  a  communications  domain,  accepting  connections  from  these  sockets  or 
exchanging  messages  with  them.  These  operations  model  a  labeled  or  unlabeled  communi¬ 
cations  graph,  and  can  be  used  in  a  wide  variety  of  communications  domains.  Sockets  can 
have  different  types  to  provide  different  semantics  of  communication,  increasing  the  flexibil¬ 
ity  of  the  model. 

Terminals  and  other  devices 

Devices  include  terminals,  providing  input  editing  and  interrupt  generation  and  output  flow 
control  and  editing,  magnetic  tapes,  disks  and  other  peripherals.  They  often  support  the 
generic  read  and  write  operations  as  well  as  a  number  of  toct/s. 

Processes 

Process  descriptors  provide  facilities  for  control  and  debugging  of  other  processes. 


t  Support  for  mapping  files  is  not  included  in  this  release. 
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8.  Generic  Operations 

Many  system  abstractions  support  the  operations  ready  write  and  ioctL  We  describe  the  basics 
of  these  common  primitives  here.  Similarly^  the  mechanisms  whereby  normally  synchronous 
operations  may  occur  in  a  non-blocking  or  asynchronous  fashion  are  common  to  ail  system- 
defined  abstractions  and  are  described  here. 


8.1.  Read  and  Write 

The  read  and  mite  system  calls  can  be  applied  to  communications  channels,  files,  terminals  and 
devices.  They  have  the  form: 

cc  =  read(fd,  buf,  nbytes); 

result  int  cc;  int  fd;  result  caddr_t  buf;  int  nbytes; 

cc  =  write(fd,  buf,  nbytes); 

result  int  cc;  int  fd;  caddrjt  buf;  int  nbytes; 

The  read  call  transfers  as  muck  data  as  possible  from  the  object  defined  by  fd  to  the  buffer  at 
address  6a/  of  size  nbytes.  The  number  of  bytes  transferred  is  returned  in  ce,  which  is  -1  if  a 
return  occurred  before  any  data  was  transferred  because  of  an  error  or  use  of  non-blocking 
operations. 

The  mite  call  transfers  data  from  the  buffer  to  the  object  defined  by  fd.  Depending  on  the  type 
of  fd,  it  is  possible  that  the  mite  call  will  accept  some  portion  of  the  provided  bytes;  the  user 
should  resubmit  the  other  bytes  in  a  later  request  in  this  case.  Error  returns  because  of  inter¬ 
rupted  or  otherwise  incomplete  operations  are  possible. 

Scattering  of  data  on  input  or  gathering  of  data  for  output  is  also  possible  using  an  array  of 
input/output  vector  descriptors.  The  type  for  the  descriptors  is  defined  in  <sys/uio.h>  as: 

struct  iovec  { 

caddr_t  iovjnsg;  /♦  base  of  a  component  */ 

int  iovjen;  /*  length  of  a  component 

}; 

The  calls  using  an  array  of  descriptors  are: 

cc  =*  readv(fd,  iov,  iovlen); 

result  int  cc;  int  fd;  struct  iovec  *iov;  int  iovlen; 

cc  »=»  writev(fd,  iov,  iovlen); 

result  int  ce;  int  fd;  struct  iovec  *iov;  int  iovlen; 

Here  iovlen  is  the  count  of  elements  in  the  iov  array. 


8.2.  Input/Output  Control 

Control  operations  on  an  object  are  performed  by  the  ioctl  operation: 

ioctl(fd,  request,  buffer); 
int  fd,  request;  caddrjt  buffer; 

This  operation  causes  the  specified  request  to  be  performed  on  the  object  fd.  The  request 
parameter  specifies  whether  the  argument  buffer  is  to  be  read,  written,  read  and  written,  or  is 
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not  needed^  and  also  the  size  of  the  buffer,  as  well  as  the  request.  Different  descriptor  types  and 
subtypes  within  descriptor  types  may  use  distinct  ioctl  requests.  For  example,  operations  on 
terminals  control  flushing  of  input  and  output  queues  and  setting  of  terminal  parameters;  opera¬ 
tions  on  disks  cause  formatting  operations  to  occur;  operations  on  tapes  control  tape  position¬ 
ing. 

The  names  for  basic  control  operations  are  defined  in  <sys/ioctl.h>. 


8.3.  Non-Blocking  and  Asynchronous  Operations 

A  process  that  wishes  to  do  non-blocking  operations  on  one  of  its  descriptors  sets  the  descriptor 
in  non-blocking  mode  as  described  in  section  5.4.  Thereafter  the  read  call  will  return  a  specific 
EWOULDBLOCK  error  indication  if  there  is  no  data  to  be  read.  The  process  maj  select  the 
associated  descriptor  to  determine  when  a  read  is  possible. 

Output  attempted  when  a  descriptor  can  accept  less  than  is  requested  will  either  accept  some  of 
the  provided  data,  returning  a  shorter  than  normal  length,  or  return  an  error  indicating  that 
the  operation  would  block.  More  output  can  be  performed  as  soon  as  a  select  call  indicates  the 
object  is  writeable. 

Operations  other  than  data  input  or  output  may  be  performed  on  a  descriptor  in  a  non-blocking 
fashion.  These  operations  will  return  with  a  characteristic  error  indicating  that  they  are  in  pro¬ 
gress  if  they  cannot  return  immediately.  The  descriptor  may  then  be  selected  for  write  to  find 
out  when  the  operation  can  be  retried.  When  select  indicates  the  descriptor  is  writeable,  a 
respecification  of  the  original  operation  will  return  the  result  of  the  operation. 
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9.  File  System 

The  file  system  abstraction  provides  access  to  a  hierarchical  file  system  structiire.  The  file  sys- 
tern  contains  directories  (each  of  which  may  contain  other  sub-directories)  as  well  as  files  and 
references  to  other  objects  such  as  devices  and  inter-process  communications  sockets. 

Each  file  is  organized  as  a  linear  array  of  bytes.  No  record  boundaries  or  system  related  infor¬ 
mation  is  present  in  a  file.  Files  may  be  read  and  written  in  a  random- access  fashion.  The  user 
may  read  the  data  in  a  directory  as  though  it  were  an  ordinary  file  to  determine  the  names  of 
the  contained  files,  but  only  the  system  may  write  into  the  directories.  The  file  system  stores 
only  a  small  amount  of  ownership,  protection  and  usage  information  with  a  file. 


9.1.  ]>|[aming 

The  file  ^(ptem  calls  take  path  name  arguments.  These  consist  of  a  zero  or  more  component  file 
names  separated  by  “/”  characters,  where  each  file  name  is  up  to  255  ASCII  characters  exclud¬ 
ing  null  s^d 

Each  pro^iess  always  has  two  naming  contexts;  one  for  the  root  directory  of  the  file  system  and 
one  for  the  current  working  directory.  These  are  used  by  the  system  in  the  filename  translation 
process.  If  a  path  name  begins  with  a  it  is  called  a  full  path  name  and  interpreted  relative 
to  the  root  directory  context.  If  the  path  name  does  not  begin  with  a  “/”  it  is  called  a  relative 
path  name  and  interpreted  relative  to  the  current  directory  context. 

The  system  limits  the  total  length  of  a  path  name  to  1024  characters. 

The  file  name  in  each  directory  refers  to  the  parent  directory  of  that  directoiy. 

The  calls 

chdii(path); 
char  *path; 

ch|‘oot(path); 
ch^  *path; 

change  the  current  working  directory  and  root  directory  context  of  a  process.  Only  the  super¬ 
user  can  change  the  root  directory  context  of  a  process. 


9.2.  Creation  and  Removal 

The  file  system  allows  directories,  files  and  special  devices,  to  be  created  and  removed  from  the 
file  system. 


9.2.1.  Directory  Creation  and  Removal 

A  directory  is  created  with  the  mkdir  system  call: 

mkdir(path,  mode); 
char  *path;  int  mode; 

and  removed  with  the  rmdir  system  call: 
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rmdiifpath); 
char  *path; 

A  directory  must  be  empty  if  it  is  to  be  deleted. 


9.2.2.  File  Creation 


Fites  are  created  with  the  open  system  call, 

fd  =  open(path,  oflag,  mode); 

result  int  fd;  char  *path;  int  oflag,  mode; 


The  pat4  parameter  specifies  the  name  of  the  file  to  be  created.  The  oflag  parameter  must 
include  Q^CREAT  from  below  to  cause  the  file  to  be  created.  The  protection  for  the  new  file  is 
specified  |n  mode.  Bits  for  oflag  are  defined  in  <8ys/file.h>: 


^define  0_RD0NLY  000 

#define  0_WR0NLY  001 

#define  0_RDWR  002 

#define  0_NDELAY  004 

#define  0_APPEND  010 

#define  0_CREAT  01000 

#define  O.TRUNC  02000 

#define  0_EXCL  04000 


/*  open  for  reading  ♦/ 

/♦  open  for  writing  */ 

/ ♦  open  for  read  &  write  ♦  / 

/*  non-blocking  open  */ 

/*  append  on  each  write  */ 

/*  open  with  file  create  ♦/ 

/*  open  with  truncation  */ 

/ ♦  error  on  create  if  file  exists  */ 


One  of  0_RDONLY,  0_WRONLY  and  0_RDWR  should  be  specified,  indicating  what  types  of 
operations  are  desired  to  be  performed  on  the  open  file.  The  operations  will  be  checked  against 
the  user’s  access  rights  to  the  file  before  allowing  the  open  to  succeed.  Specifying  0_APPEND 
causes  writes  to  automatically  append  to  the  file.  The  flag  0_CREAT  causes  the  file  to  be 
created  if  it  does  not  exist,  with  the  specified  mode,  owned  by  the  current  user  and  the  group  of 
the  containing  directory. 

If  the  open  specifies  to  create  the  file  with  0_EXCL  and  the  file  already  exists,  then  the  open 
will  fail  without  affecting  the  file  in  any  way.  This  provides  a  simple  exclusive  access  facility. 


9.2.3.  Creating  References  to  Devices 

The  file  system  allows  entries  which  reference  peripheral  devices.  Peripherals  are  distinguished 
as  block  or  character  devices  according  by  their  ability  to  support  block-oriented  operations. 
Devices  are  identified  by  their  ‘‘major”  and  “minor”  device  numbers.  The  major  device  number 
determines  the  kind  of  peripheral  it  is,  while  the  minor  device  number  indicates  one  of  possibly 
many  peripherals  of  that  kind.  Structured  devices  have  all  operations  performed  internally  in 
“block”  quantities  while  unstructured  devices  often  have  a  number  of  special  ioetl  operations, 
and  may  have  input  and  output  performed  in  large  units.  The  mknod  call  creates  special 
entries: 


mknod(path,  mode,  dev); 
char  *path;  int  mode,  dev; 

where  mode  is  formed  from  the  object  type  and  access  permissions.  The  parameter  dev  is  a 
configuration  dependent  parameter  used  to  identify  specific  character  or  block  i/o  devices. 
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9.2*4.  File  and  Device  Removal 

A  reference  to  a  file  or  special  device  may  be  removed  with  the  unlink  call, 

unlink(path); 
char  *path; 

The  caller  must  have  write  access  to  the  directory  in  which  the  file  is  located  for  this  call  to  be 
successful. 


9.3.  Reading  and  Modifying  File  Attributes 

Detailed  information  about  the  attributes  of  a  file  may  be  obtained  with  the  calls: 

#include  <sy8/8tat.h> 

8tat(path,  stb); 

char  *path;  resxilt  struct  stat  *stb; 
f8tat(fd,  stb); 

int  fd;  result  struct  stat  *8tb; 

The  »tat  structure  includes  the  file  type,  protection,  ownership,  access  times,  size,  and  a  count  of 
hard  links.  If  the  file  is  a  symbolic  link,  then  the  status  of  the  link  itself  (rather  than  the  file 
the  link  references)  may  be  found  using  the  Utat  call; 

lstat(path,  stb); 

char  *path;  result  struct  stat  *stb; 

Newly  created  files  are  assigned  the  user  id  of  the  process  that  created  it  and  the  group  id  of  the 
directory  (n  which  it  was  created.  The  ownership  of  a  file  may  be  changed  by  either  of  the  calls 

c^pwn(path,  owner,  group); 
chpr  *path;  int  owner,  group; 

fchown(fd,  owner,  group); 
int  fd,  owner,  group; 

In  addition  to  ownership,  each  file  has  three  levels  of  access  protection  associated  with  it.  These 
levels  are  owner  relative,  group  relative,  and  global  (all  users  and  groups).  Each  level  of  access 
has  separate  indicators  for  read  permission,  write  permission,  and  execute  permission.  The  pro¬ 
tection  bits  associated  with  a  file  may  be  set  by  either  of  the  calls: 

chmod(path,  mode); 
char  *path;  int  mode; 

fchmod(fd,  mode); 
int  fd,  mode; 

where  mode  is  a  value  indicating  the  new  protection  of  the  file.  The  file  mode  is  a  three  digit 
octal  number.  Bach  digit  encodes  read  access  as  4,  write  access  as  2  and  execute  access  as  1, 
or’cd  together.  The  0700  bits  describe  owner  access,  the  070  bits  describe  the  access  rights  for 
processes  in  the  same  group  as  the  file,  and  the  07  bits  describe  the  access  rights  for  other 
processes. 
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Three  additional  bits  exist:  the  04000  ^^set-user-id**  bit  can  be  set  on  an  executable  file  to  cause 
the  effective  user-id  of  a  process  which  executes  the  file  to  be  set  to  the  owner  of  that  file;  the 
02000  bit  has  a  similar  effect  on  the  effective  group*id«  The  01000  bit  causes  an  image  of  an 
executable  program  to  be  saved  longer  than  would  otherwise  be  normal;  this  ^^sticky^*  bit  is  a 
hint  to  the  system  that  a  program  is  heavily  used* 

Finally^  the  access  and  modify  times  on  a  file  may  be  set  by  the  call: 

utime8(path9  tvp); 

char  *path;  struct  timeva!  ’^tvp[2]; 

This  is  particularly  useful  when  moving  files  between  media,  to  preserve  relationships  between 
the  times  the  file  was  modified. 

0.4*  Links  and  Renaming 

Links  allow  multiple  names  for  a  file  to  exist.  Links  exist  independently  of  the  file  linked  to. 

Two  tjrpes  of  links  exist,  hard  links  and  tymbolie  links.  A  hard  link  is  a  reference  counting 
mechanism  that  allows  a  file  to  hare  multiple  names  within  the  same  file  system.  Symbolic 
links  cause  string  substitution  during  the  pathname  interpretation  process. 

Hard  links  and  symbolic  links  have  different  properties.  A  hard  link  insures  the  target  file  will 
always  be  accessible,  even  after  its  original  directory  entry  is  removed;  no  such  guarantee  exists 
for  a  symbolic  link.  Symbolic  links  can  span  file  systems  boundaries. 

The  following  calls  create  a  new  link,  named  paths,  to  path!'. 

link(pathl,  path2); 
char  *pathl,  ‘»path2; 

symlink(pathl,  path2); 
char  *pathl,  *path2; 

The  unlink  primitive  may  be  used  to  remove  either  type  of  link. 

If  a  file  is  a  symbolic  link,  the  “value"  of  the  link  may  be  read  with  the  readlink  call, 

lep  readlink(path,  buf,  bufsize); 

result  int  len;  result  char  *path,  *buf;  int  bufsize; 

This  call  returns,  in  bt^,  the  null-terminated  string  substituted  into  pathnames  passing  through 

path. 

Atomic  renaming  of  file  system  resident  objects  is  possible  with  the  rename  call: 

rename(oidname,  newname); 
char  *oldname,  *newname; 

where  both  oldname  and  netraame  must  be  in  the  same  file  system.  If  neumame  exists  and  is  a 
directory,  then  it  must  be  empty. 

9.5.  Extension  and  Truncation 

Files  are  created  with  zero  length  and  may  be  extended  simply  by  writing  or  appending  to 
them.  While  a  file  is  open  the  system  maintmns  a  pointer  into  the  file  indicating  the  current 
location  in  the  file  associated  with  the  descriptor.  This  pointer  may  be  moved  about  in  the  file 
in  a  random  access  fashion.  To  set  the  current  offset  into  a  file,  the  Ueek  call  may  be  used. 
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oldoSset  »  Iseek(fd,  offset,  type); 

result  offjt  oldo&et;  int  fd;  off_t  offset;  int  type; 

where  type  is  given  in  <sy8/file.h>  as  one  of, 

#define  L_SET  0  /♦set  absolute  file  ofifeet  */ 

^define  L_INCR  1  /♦  set  file  ofibet  relative  to  current  position  */ 

#define  L_XTND  2  /*  set  offset  relative  to  cnd-of-file  */ 

The  call  “lseek(fd,  0,  L_INCR)”  returns  the  current  offset  into  the  file. 

Files  may  have  “holes”  in  them.  Holes  are  void  areas  in  the  linear  extent  of  the  file  where  data 
has  never  been  written.  These  may  be  created  by  seeking  to  a  location  in  a  file  past  the  current 
end'of-file  and  writing.  Holes  are  treated  by  the  system  as  sero  valued  bytes. 

A  file  may  be  truncated  with  either  of  the  calls: 

truncate(path,  length); 
char  ♦path;  int  length; 

ftruncate(fd,  length); 
int  fd,  length; 

reducing  the  size  of  the  specified  file  to  length  bytes. 


9.0.  Checking  Accessibility 


A  process  running  with  different  real  and  effective  user  ids  may  interrogate  the  accessibility  of  a 
file  to  the  real  user  by  using  the  accett  call: 

accessible  *=  acce8s(path,  how); 
result  int  accessible;  char  ♦path;  int  how; 


Here  how  is  constructed  by  or’ing  the  following  bits,  defined  in  <sys/file.h>: 


#define  F_OK 
#define  X_OK 
#define  W_OK 
#define  R_OK 


0  /*  file  exists  ♦/ 

1  /*  file  is  executable  ♦/ 

2  /*  file  is  writable  ♦/ 

4  /*  file  is  readable  */ 


The  presence  or  absence  of  advisory  locks  does  not  affect  the  result  of  accett . 


0.7.  Locking 

The  file  system  provides  basic  facilities  that  allow  cooperating  processes  to  synchronize  their 
access  to  shared  files.  A  process  may  place  an  advisory  read  or  write  lock  on  a  file,  so  that  other 
cooperating  processes  may  avoid  interfering  with  the  process’  access.  This  simple  mechanism 
provides  locking  with  file  granularity.  More  granular  locking  can  be  built  using  the  IPC  facili¬ 
ties  to  provide  a  lock  manager.  The  system  does  not  force  processes  to  obey  the  locks;  they  are 
of  an  advisory  nature  only. 

Locking  is  performed  after  an  open  call  by  applying  the  flock  primitive, 

flock(fd,  how); 
int  fd,  how; 

where  the  how  parameter  is  formed  from  bits  defined  in  <sys/file.h>: 
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#define  LOCK_SH  1 

#define  LOCKJiX  2 

#define  LOCK^NB  4 

#define  LOCK_UN  8 


/*  shared  lock  ♦/ 

/♦  exclusive  lock  */ 

/*  don’t  block  when  locking  ♦/ 
/♦  unlock  ♦/ 


Successive  lock  calls  may  be  used  to  increase  or  decrease  the  level  of  locking.  If  an  object  is 
currently  locked  by  another  process  when  a  flock  call  is  made,  the  caller  will  be  blocked  until  the 
current  lock  owner  releases  the  lock;  this  may  be  avoided  by  including  LOCK^NB  in  the  how 
parameter.  Specifying  LOCK_UN  removes  all  locks  associated  with  the  descriptor.  Advisory 
locks  held  by  a  process  are  automatically  deleted  when  the  process  terminates. 


9«8.  Disk  Quotas 

As  an  optional  facility,  each  file  system  may  be  requested  to  impose  limits  on  a  user’s  disk 
usage.  Two  quantities  are  limited:  the  total  amount  of  disk  space  which  a  user  may  allocate  in 
a  file  system  and  the  total  number  of  files  a  user  may  create  in  a  file  system.  Quotas  are 
expressed  as  hard  limits  and  ooft  limits.  A  hard  limit  is  always  imposed;  if  a  user  would  exceed 
a  hard  limit,  the  operation  which  caused  the  resource  request  will  fail.  A  soft  limit  results  in  the 
user  receiving  a  warning  message,  but  with  allocation  succeeding.  Facilities  are  provided  to  turn 
soft  limits  into  hard  limits  if  a  user  has  exceeded  a  soft  limit  for  an  unreasonable  period  of  time. 

To  enable  disk  quotas  on  a  file  system  the  ectquota  call  is  used: 

setquota(special,  file); 
char  ^special,  *file; 

where  special  refers  to  a  structured  device  file  where  a  mounted  file  system  exists,  and  file  refers 
to  a  disk  quota  file  (residing  on  the  file  system  associated  with  special)  from  which  user  quotas 
should  be  obtained.  The  format  of  the  disk  quota  file  is  implementation  dependent. 

To  manipulate  disk  quotas  the  quota  call  is  provided: 

#include  <sys/quota.h> 

quota(cmd,  uid,  arg,  addr); 
int  cmd,  uid,  arg;  caddrj;  addr; 

The  indicated  cmd  is  applied  to  the  user  ID  uid.  The  parameters  arg  and  addr  are  command 
specific.  The  file  <sy8/quota.h>  contains  definitions  pertinent  to  the  use  of  this  call. 
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10*  Interprocess  Communications 


10*1.  Interprocess  Communication  Primitives 


10*1*1*  Communication  Domains 

The  system  provides  access  to  an  extensible  set  of  communication  domains.  A  communication 
domain  is  identified  by  a  manifest  constant  defined  in  the  file  <sy8/socket.h>.  Important 
standard  domains  supported  by  the  system  are  the  UNIX  domain,  AF_UNIX,  for  communication 
tvithin  the  system,  and  the  “internet'’  domain  for  communication  in  the  DARPA  internet, 
AFJNET.  Other  domains  can  be  added  to  the  system. 

10*1.2*  Socket  Types  and  Protocols 

Witiun  a  domain^  communication  takes  place  between  communication  endpoints  known  as  sock* 
ctSs  Each  socket  has  the  potential  to  exchange  information  with  other  sockets  within  the 
domain. 

Each  socket  has  an  associated  abstract  type,  which  describes  the  semantics  of  communication 
using  that  socket.  Properties  such  as  reliability,  ordering,  and  prevention  of  duplication  of  mes¬ 
sages  are  determined  by  the  type.  The  basic  set  of  socket  types  is  defined  in  <sys/socket.h>: 

/♦  Standard  socket  types  */ 

^define  SOCK^DGRAM  1  /♦  datagram  */ 

^define  SOCK_STREAM  2  /♦  virtual  circuit  ♦/ 

^define  SOCK_RAW  3  /♦  raw  socket  */ 

^define  SOCK_RDM  4  /*  reliably-delivered  message  */ 

^define  SOCK_SEQPACKET  5  /*  sequenced  packets  */ 

The  SOCKJDGRAM  type  models  the  semantics  of  datagrams  in  network  communication:  mes¬ 
sages  may  be  lost  or  duplicated  and  may  arrive  out-of-order.  The  SOCK_RDM  type  models  the 
semantics  of  reliable  datagrams:  messages  arrive  unduplicated  and  in-order,  the  sender  is 
notified  if  messages  are  lost.  The  send  and  receive  operations  (described  below)  generate 
reliable/unreliable  datagrams.  The  SOCK^STREAM  type  models  connection- based  virtual  cir^ 
cuits:  two-way  byte  streams  with  no  record  boundaries.  The  SOCK_SEQPACKET  type  models 
a  connection-based,  full-duplex,  reliable,  sequenced  packet  exchange;  the  sender  is  notified  if 
messages  are  lost,  and  messages  are  never  duplicated  or  presented  out-of-order.  Users  of  the 
last  two  abstractions  may  use  the  facilities  for  out-of-band  transmission  to  send  out-of-band 
data. 

SOCK^RAW  is  used  for  unprocessed  access  to  internal  network  layers  and  interfaces;  it  has  no 
specific  semantics. 

Other  socket  types  can  be  defined.! 

Each  socket  may  have  a  concrete  protocol  associated  with  it.  This  protocol  is  used  within  the 
domain  to  provide  the  semantics  required  by  the  socket  type.  For  example,  within  the 

t  This  release  docs  not  support  the  SOCK_PDM  and  SOCK^SEQPACKET  types. 
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* ‘internet’ •  domain,  the  SOCK_DGRAM  type  may  be  implemented  by  the  UDP  user  datagram 
protocol,  and  the  SOCK_STREAM  type  may  be  implemented  by  the  TCP  transmission  control 
protocol,  while  no  standard  protocols  to  provide  SOCKJRDM  or  SOCKJSEQPACKET  sockets 
exist. 


10.1.3.  Socket  Creation^  Naming,  and  Service  Establishment 

Sockets  may  be  connected  or  unconnected^  An  unconnected  socket  descriptor  is  obtained  by  the 
socket  call: 

s  =•  8ocket(domain,  type,  protocol); 
result  int  s;  int  domain,  type,  protocol; 

An  unconnected  socket  descriptor  may  yield  a  connected  socket  descriptor  in  one  of  two  ways: 
either  by  actively  connecting  to  another  socket,  or  by  becoming  associated  with  a  name  in  the 
communications  domain  and  accepting  a  connection  from  another  socket. 

To  accept  connections,  a  socket  must  first  have  a  binding  to  a  name  within  the  communications 
domain.  Such  a  binding  is  established  by  a  bind  call: 

bind(s,  name,  namelen); 

int  s;  char  ^narne;  int  namelen; 

A  socket^s  bound  name  may  be  retrieved  with  a  getsockname  call: 

getsockname(s,  name,  namelen); 

int  s;  result  caddr^t  name;  result  int  ^namelen; 

while  the  peer’s  name  can  be  retrieved  with  getpeernamc: 

getpeername(s,  name,  namelen); 

int  s;  result  caddr.t  name;  result  int  ^namelen; 

Domains  may  support  sockets  with  several  names. 


10.1.4.  Accepting  Connections 

Once  a  binding  is  made,  it  is  possible  to  listen  for  connections: 

listen(s,  backlog); 
int  s,  backlog; 

The  beektog  specifies  the  maximum  count  of  connections  that  can  be  simultaneously  queued 
avaiting  acceptance. 

An  accept  call: 

t  accept(s,  name,  anamelen); 

result  int  t;  int  s;  result  caddr_t  name;  result  int  ^anamelen; 
returns  a  descriptor  for  a  neir,  connected,  socket  from  the  queue  of  pending  connections  on  e. 
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10.1 .5.  Making  Connections 

An  active  connection  to  a  named  socket  is  made  by  the  connect  call: 

connect(s,  name,  namelen); 
int  s;  caddrjt  name;  int  namelen; 

It  is  also  possible  to  create  connected  pairs  of  sockets  without  using  the  domain’s  name  space  to 
rendezvous;  this  is  done  with  the  tocketpatr  calif: 

socketpair(d,  type,  protocol,  sv); 
int  d,  type,  protocol;  result  int  8v(2); 

Here  the  returned  $v  descriptors  correspond  to  those  obtained  with  accept  and  eonnect. 

The  call 

pipe(pv); 
result  int  pv[2]; 

creates  a  pair  of  SOCK_STREAM  sockets  in  the  UNIX  domain,  with  pv[0)  only  writeable  and 
pv[l]  only  readable. 

10*1.0.  Sending  and  Receiving  Data 

Messages  may  be  sent  from  a  socket  by: 

cc  =  8endto(s,  buf,  len,  flags,  to,  tolen); 

result  int  cc;  int  s;  caddrjt  buf;  int  len,  flags;  caddrjt  to;  int  tolen; 

socket  is  not  connected  or: 

cc  =  send(s,  buf,  len,  flags); 
result  int  cc;  int  s;  caddr_t  buf;  int  len,  flags; 

socket  is  connected.  The  corresponding  receive  primitives  are: 

msglen  «  recvfrom(s,  buf,  len,  flags,  from,  fromlenaddr); 
result  int  msglen;  int  s;  result  caddrjt  buf;  int  len,  flags; 
result  caddrjt  from;  result  int  *fromlenaddr; 

msglen  ■■  recv(s,  buf,  len,  flags); 

result  int  msglen;  int  s;  result  caddrjt  buf;  int  len,  flags; 

In  the  unconnected  case,  the  parameters  to  and  tolen  specify  the  destination  or  source  of  the 
message,  while  the  ftotn  parameter  stores  the  source  of  the  message,  and  ^/fomlenaddf  initially 
gives  the  size  of  the  from  bufier  and  is  updated  to  reflect  the  true  length  of  the  from  address. 

All  calls  cause  the  message  to  be  received  in  or  sent  from  the  message  buffer  of  length  len  bytes, 
starting  at  address  buf.  The  flago  specify  peeking  at  a  message  without  reading  it  or  sending  or 
receiving  high-priority  out-of-band  messages,  as  follows: 


o  „ 


the 


if  the 


and 


t  This  release  supports  taeketpair  creation  only  in  the  “unix” 


communication  domain. 
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#define  MSG_PEEK  0x1  /*  peek  at  incoming  message  */ 

^define  MSGjOOB  0x2  /*  process  out-of-band  data  */ 


10.1.7.  Scatter/ Gather  and  Exchanging  Access  Rights 

It  15  possible  to  scatter  and  gather  data  and  to  exchange  access  rights  with  messages.  When 
either  of  these  operations  is  involved^  the  number  of  parameters  to  the  call  becomes  large.  Thus 


the  system  defines  a  message  header  structure, 
parameters  to  the  calls: 

in  <sys/socket.h>,  which  is  used  to  contain  the 

struct  msghdr  { 

caddrjt 

msg_name; 

f*  optional  address  *( 

int 

msg_namelen; 

f*  sire  of  address  ♦/ 

struct 

iov  *msg_iov; 

/♦  scatter/gather  array  */ 

int 

msgjovlen; 

/*  ^  elements  in  msg_iov  */ 

caddrjt 

msg  aecrights; 

/*  access  lights  sent/received  */ 

int 

msg  accrightslen; 

/*  size  of  msg  aecrights 

}; 

Here  msg_namc  and  mtgjnamden  specify  the  source  or  destination  address  if  the  socket  is 
unconnected;  m$g_name  may  be  given  as  a  null  pointer  if  no  names  are  desired  or  required.  The 
mtgjiov  and  msg_iovten  describe  the  scatter/gather  locations,  as  described  in  section  8.3.  Access 
rights  to  be  sent  along  with  the  message  are  specified  in  msg  aecrights,  which  has  length 
m$g^accright»len.  In  the  “unix”  domain  these  are  an  array  of  integer  descriptors,  taken  from 
the  sending  process  and  duplicated  in  the  receiver. 

This  structure  is  used  in  the  operations  »endm»g  and  recvmsg: 

8endmsg(s,  msg,  flags); 

int  s;  struct  msghdr  *msg;  int  flags; 

msglen  =  recvmsg(s,  msg,  flags); 

result  int  msglen;  int  s;  result  struct  msghdr  *msg;  int  flags; 


10.1.8.  Using  Read  and  Write  with  Sockets 

The  normal  UNIX  read  and  write  calls  may  be  applied  to  connected  sockets  and  translated  into 
$end  and  receive  calls  from  or  to  a  single  area  of  memory  and  discarding  any  rights  received.  A 
process  may  operate  on  a  virtual  circuit  socket,  a  terminal  or  a  file  with  blocking  or  non- 
blocking  input/output  operations  without  distinguishing  the  descriptor  type. 

10.1.9.  Shutting  Down  Halves  of  Full-Duplex  Connections 

A  process  that  has  a  full-duplex  socket  such  as  a  virtual  circuit  and  no  longer  wishes  to  read 
from  or  write  to  this  socket  can  give  the  call: 

8hutdown(s,  direction); 
int  s,  direction; 

where  direction  is  0  to  not  read  further,  1  to  not  write  further,  or  2  to  completely  shut  the 
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10*1  .lO*  Socket  and  Protocol  Options 

Sockets^  and  their  underlying  communication  protocols,  may  support  options.  These  options 
may  be  used  to  manipulate  implementation  specific  or  non-standard  facilities.  The  getsockopt 
and  sotsockopt  calls  are  used  to  control  options: 

getsockopt(s,  level,  optname,  optval,  optlen); 

int  8,  level,  optname;  result  caddrjt  optval;  result  int  soptlen; 

8etsockopt(s,  level,  optname,  optval,  optlen); 
int  8,  level,  optname;  caddrjt  optval;  int  optlen; 

The  option  optname  is  interpreted  at  the  indicated  protocol  level  for  socket  s.  If  a  value  is 
specified  with  optval  and  optlen^  it  is  interpreted  by  the  software  operating  at  the  specified  level. 
The  level  SOL_SOCKET  is  reserved  to  indicate  options  maintained  by  the  socket  facilities. 
Other  level  values  indicate  a  particular  protocol  which  is  to  act  on  the  option  request;  these 
values  are  normally  interpreted  as  a  “protocol  number”. 


10.2.  UNIX  Domain 

This  section  describes  briefly  the  properties  of  the  UNIX  communications  domain. 


10*2*1*  Types  of  Sockets 

In  the  UNIX  domain,  the  SOCK_J5TREAM  abstraction  provides  pipe-like  facilities,  while 
SOCKJ>GRAM  provides  datagrams  -  unreliable  message-style  communications. 


10*2 *2*  Naming 

Socket  names  are  strings  and  may  appear  in  the  UNIX  file  system  name  space  through  portalst. 


10*2*3*  Access  Rights  Transmission 

The  ability  to  pass  UNIX  descriptors  with  messages  in  this  domain  allows  migration  of  service 
within  the  system  and  allows  user  processes  to  be  used  in  building  system  facilities. 


10*3.  INTERNET  Domain 

This  section  describes  briefly  how  the  INTERNET  domain  is  mapped  to  the  model  described  In 
this  section.  More  information  will  be  found  in  the  Networking  Implementation  Notes  in  the 
System  Internals  Manual. 

t  The  current  implementation  of  the  UNIX  domain  embeds  bound  sockets  in  the  UNIX  file  system 
name  space;  this  is  a  side  effect  of  the  implementation. 
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10.3.1.  Socket  Types  and  Protocols 

SOCK_STREAM  is  supported  by  the  INTERNET  TCP  protocol;  SOCK_DGRAM  by  the  UDP 
protocol.  The  SOCK_SEQPACKET  has  no  direct  INTERNET  family  analogue;  a  protocol 
based  on  one  from  the  XEROX  NS  family  and  layered  on  top  of  IP  could  be  implement^  to  fill 
this  gap. 


10*3*2.  Socket  Naming 

Sockets  in  the  INTERNET  domain  have  names  composed  of  the  32  bit  internet  address,  and  a 
16  bit  port  number.  Options  may  be  used  to  provide  source  routing  for  the  address,  security 
options,  or  additional  addresses  for  subnets  of  INTERNET  for  which  the  basic  32  bit  addresses 
are  insufficient. 


10.3.3.  Access  Rights  Transmission 

No  access  rights  transmission  facilities  are  provided  in  the  INTERNET  domain. 


10*3.4.  Raw  Access 

The  INTERNET  domain  allows  the  super-user  access  to  the  raw  facilities  of  the  various  net¬ 
work  interfaces  and  the  various  internal  layers  of  the  protocol  implementation.  This  allows 
administrative  and  debugging  functions  to  occur.  These  interfaces  are  modeled  as  S0CK_RAW 
sockets. 
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1 1  •  Devices 

The  system  uses  a  collection  of  device- drivers  to  access  attached  peripherals.  Such  devices  are 
grouped  into  two  classes:  structured  devices  on  which  block-oriented  input/output  operations 
occur,  and  unstructured  devices  (the  rest). 

ll.l*  Structured  Devices 

Structured  devices  include  disk  and  tape  drives,  and  are  accessed  through  a  system  buffer¬ 
caching  mechanism,  which  permits  them  to  be  accessed  as  ordinary  files  are,  performing  reads 
and  writes  as  necessary  to  allow  random-access. 

The  mount  command  in  the  system  allows  a  structured  device  containing  a  file  system  volume 
to  be  accessed  through  the  UNDC  file  system  calls. 

Tape  drives  also  typically  provide  a  structured  interface,  although  this  is  rarely  used. 


11  •2.  Unstructured  Devices 

Unstructured  devices  are  those  devices  which  do  not  support  a  randomly  accessed  block  struc¬ 
ture. 

Communications  lines,  raster  plotters,  normal  magnetic  tape  access  (in  large  or  variable  size 
blocks),  and  access  to  disk  drives  permitting  large  block  transfers  and  special  operations  like 
disk  formatting  and  labelling  all  use  unstructured  device  interfaces. 

The  writing  of  devices  for  unstructured  devices  other  than  communications  lines  is  described  in 
the  Device  Driver  Manual  in  the  System  Internals  Manual. 
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12.  Debugging  Support 

The  ptrace  facility  of  version  7  UNIX  is  provided  in  this  release.  Planned  enhancements  which 
would  allow  a  descriptor-based  process  control  facility  have  not  been  implemented. 
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Part  in  —  Summary  of  Facilities 


Appendix  A.  Summary  of  Facilities 


A.I.  Kernel  Primitives 


A.I.I.  Process  Naming  and  Protection 


sethostid 

set  UNIX  host  id 

gethostid 

get  UNIX  host  id 

sethostname 

set  UNIX  host  name 

gethostname 

get  UNIX  host  name 

getpid 

get  process  id 

fork 

create  nev  process 

exit 

terminate  a  process 

execve 

execute  a  different  process 

getuid 

get  user  id 

geteuid 

get  effective  user  id 

setreuid 

set  real  and  effective  user  id’s 

getpd 

get  accounting  group  id 

gete^d 

get  effective  accounting  group  id 

getgroups 

get  access  group  set 

setregid 

set  real  and  effective  group  id’s 

setgroups 

set  access  group  set 

getpgrp 

get  process  group 

sctpgrp 

set  process  group 

A.  1.2.  Memory  Management 

<mmaii.h>  memoty  management  definitions 

sbrk  change  data  section  size 

sstkf  change  stack  section  size 

t  Not  supported  in  the  1.1  Sun  release. 
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getpagesize 

mmapt 

mremapt 

munmapt 

mprotectf 

madvisef 

mincoref 


get  memory  page  size 

map  pages  of  memory 

remap  pages  in  memory 

unmap  memory 

change  protection  of  pages 

give  memory  management  advice 

determine  core  residency  of  pages 


A.l*3.  Signals 

<signaLh> 

sigvec 

kill 

killpgrp 

sigblock 

sigsetmask 

sigpause 

sigstack 


signal  definitions 
set  handler  for  signal 
send  signal  to  process 
send  signal  to  process  group 
block  set  of  signals 
restore  set  of  blocked  signals 
wait  for  signals 
set  software  stack  for  signals 


A.  1.4.  Timing  and  Statistics 


<sys/time.h> 

gettimeofday 

settimeofday 

get i timer  ^ 

setitimer 

profit 


A.  1.5.  Descriptors 

getdtablesize 

dup 

dup2 

close 

select 

fcntl 


time-related  definitions 

get  current  time  and  timezone 

set  current  time  and  timezone 

read  an  interval  timer 

get  and  set  an  interval  timer 

profile  process 


descriptor  reference  table  size 
duplicate  descriptor 
duplicate  to  specified  index 
close  descriptor 
multiplex  input/output 
control  descriptor  options 


t  Not  supported  in  the  1.1  Sun  release. 
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A.1.6.  Resource  Controls 


<a3r9/reaource.h> 

getpriority 

setpriority 

getrusage 

getrlimit 

setrlimit 


resource-related  definitions 
get  process  priority 
set  process  priority 
get  resource  usage 
get  resource  limitations 
set  resource  limitations 


A«l*7*  System  Operation  Support 


mount 

mount  a  device  file  system 

swapon 

add  a  swap  device 

umount 

umount  a  file  system 

sync 

flush  system  caches 

reboot 

reboot  a  machine 

acct 

specify  accounting  file 

A*2.  System  Facilities 


A*2.1.  Generic  Operations 


read 

write 

<ays/uio.h> 

readv 

writev 

<By8/ioctl.h> 

ioctl 


read  data 
write  data 

scatter-gather  related  definitions 
scattered  data  input 
gathered  data  output 
standard  control  operations 
device  control  operation 


A*2.2.  File  System 


Operations  marked  with  a  *  exist  in  two  forms:  as  shown,  operating  on  a  file  name,  and  operat¬ 
ing  on  a  file  descriptor,  when  the  name  is  preceded  with  a  “f”. 


<sys/file.h> 

chdir 

chroot 

mkdir 

rmdir 

open 

mknod 

unlink 

stat* 


file  system  definitions 
change  directory 
change  root  directory 
make  a  directory 
remove  a  directory 
open  a  new  or  existing  file 
make  a  special  file 
remove  a  link 
return  status  for  a  file 
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Istat 

returned  status  of  link 

chown* 

change  owner 

chmod* 

change  mode 

utimes 

change  access/modify  times 

link 

make  a  hard  link 

symlink 

make  a  symbolic  link 

readlink 

read  contents  of  symbolic  link 

rename 

change  name  of  file 

Iseek 

reposition  within  file 

truncate* 

truncate  file 

access 

determine  accessibility 

flock 

lock  a  file 

A.2.3.  Interprocess  Communications 

<sys/socket.h> 
socket 
bind 

getsockname 
listen 
accept 
connect 
socketpair 
sendto 
send 
recvfrom 
reev 

sendmsg 
recvmsg 
shutdown 
getsockopt 
setsockopt 


A.2.4.  Devices 


A.2.6.  Debugging  Support 


standard  definitions 

create  socket 

bind  socket  to  name 

get  socket  name 

allow  queueing  of  connections 

accept  a  connection 

connect  to  peer  socket 

create  pair  of  connected  sockets 

send  data  to  named  socket 

send  data  to  connected  socket 

receive  data  on  unconnected  socket 

receive  data  on  connected  socket 

send  gathered  data  and/or  rights 

receive  scattered  data  and/or  rights 

partially  close  full-duplex  connection 

get  socket  option 

set  socket  option 


40 


Revision  E  of  7  January  1984 


INTRO  (2) 


SYSTEM  CALLS 


INTRO(2) 


NAME 

intro  -  introduction  to  system  calls  and  error  numbers 
SYNOPSIS 

^Include  <errno«h> 

DESCRIPTION 

This  section  describes  all  of  the  system  calls.  Most  of  these  calls  have  one  or  more  error  returns, 
error  condition  is  indicated  by  an  otherwise  impossible  return  value.  This  is  almost  always  -1; 
individual  descriptions  specify  the  details. 

^  with  normal  arguments,  all  return  codes  and  values  from  functions  are  of  type  integer  unless 
otherwise  noted.  An  error  number  is  also  made  avmlable  in  the  external  variable  errno,  which  is 
not  cleared  on  successful  calb.  Thus  errno  should  be  tested  only  after  an  error  has  occurred. 

'I^he  following  is  a  complete  list  of  the  errors  and  their  names  as  given  in  <  errno. A>. 

Error  0 
Unused. 

1  EPERM  Not  owner 

Typically  this  error  indicates  an  attempt  to  modify  a  file  in  some  way  forbidden  except  to 
its  owner  or  super-user.  It  is  also  returned  for  attempts  by  ordinary  users  to  do  things 
allowed  only  to  the  supe>user. 

2  ENOENT  No  such  file  or  directory 

This  error  occurs  when  a  file  name  is  specified  and  the  file  should  exist  but  doesn’t,  or 
when  one  of  the  directories  in  a  path  name  does  not  exist. 

3  ESRCH  No  such  process 

The  process  whose  number  was  given  to  kill  and  p trace  does  not  exist,  or  is  already  dead. 

4  EINTR  Interrupted  system  call 

An  asynchronous  signal  (such  as  interrupt  or  quit),  which  the  user  has  elected  to  catch, 
occurred  during  a  system  call.  If  execution  is  resumed  after  processing  the  signal,  it  will 
appear  as  if  the  interrupted  system  call  returned  this  error  condition. 

5  EIO  I/O  error 

Some  physical  I/O  error  occurred  during  a  read  or  write.  This  error  may  in  some  cases 
occur  on  a  call  following  the  one  to  which  it  actually  applies. 

6  ENXIO  No  such  device  or  address 

I/O  on  a  special  file  refers  to  a  subdevice  which  does  not  exist,  or  beyond  the  limits  of  the 
device.  It  may  also  occur  when,  for  example,  an  illegal  tape  drive  unit  number  is  selected 
or  a  disk  pack  is  not  loaded  on  a  drive. 

7  E2BIG  Arg  list  too  long 

An  argument  list  longer  than  10240  bytes  is  presented  to  ezecve, 

8  ENOEXEC  Exec  format  error 

A  request  is  made  to  execute  a  file  which,  ^though  it  has  the  appropriate  permissions, 
does  not  start  with  a  valid  magic  number,  see  a.ou^(5). 

9  EBADF  Bad  file  number 

Either  a  file  descriptor  refers  to  no  open  file,  or  a  read  (reap,  write)  request  is  made  to  a 
file  which  is  open  only  for  writing  (resp.  reading). 

10  ECHILD  NochUdren 

Wait  and  the  process  has  no  living  or  unwaited-for  children. 

11  EAGAJN  No  more  processes 

In  a  fork,  the  system’s  process  table  is  full  or  the  user  is  not  allowed  to  create  any  more 
processes. 
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12  ENOMEM  Not  enough  core 

During  an  txecve  or  break,  a  program  asks  for  more  core  or  swap  8p2M:e  than  the  system  is 
able  to  supply.  A  lack  of  swap  space  is  normally  a  temporary  condition,  however  a  lack 
of  core  is  not  a  temporary  condition;  the  maximum  size  of  the  text,  data,  and  stack  seg* 
ments  is  a  system  parameter. 

13  EACCES  Permission  denied 

An  attempt  was  made  to  access  a  file  in  a  way  forbidden  by  the  protection  system. 

14  EFAULT  Bad  address 

The  system  encountered  a  hardware  fault  in  attempting  to  access  the  arguments  of  a  sys¬ 
tem  call. 

16  ENOTBLK  Block  device  required 

A  plain  file  was  mentioned  where  a  block  device  was  required,  e.g.  in  m^unL 

16  EBUSY  Mount  device  busy 

An  attempt  to  mount  a  device  that  was  already  mounted  or  an  attempt  was  made  to 
dismount  a  device  on  which  there  is  an  active  file  directory,  (open  file,  current  directory, 
mounted-on  file,  active  text  segment). 

17  EEXIST  File  exists 

An  existing  file  was  mentioned  in  an  inappropriate  context,  e.g.  link. 

18  EXDEV  Cross-device  link 

A  hard  link  to  a  file  on  another  device  was  attempted. 

19  ENODEV  No  such  device 

An  attempt  was  made  to  apply  an  inappropriate  astern  call  to  a  device;  e.g.  read  a 
write-only  device. 

20  ENOTDIR  Not  a  directory 

A  non-directory  was  specified  where  a  directory  is  required,  for  example  in  a  path  name 
or  as  an  argument  to  ehdir. 

21  EISDIR  Is  a  directory 

An  attempt  to  write  on  a  directory. 

22  EINVAL  Invalid  argument 

Some  invalid  argument:  dismounting  a  non-mounted  device,  mentioning  an  unknown  sig¬ 
nal  in  signal,  reading  or  writing  a  file  for  which  seek  has  generated  a  negative  pointer. 
Also  set  by  math  functions,  see  in(ro(3). 

23  ENFILE  File  table  overfloii^ 

The  system^s  table  of  open  files  is  full,  and  temporarily  no  more  opens  can  be  accepted. 

24  EMFILE  Too  many  open  fite^ 

Customary  configuration  limit  is  20  per  process. 

25  ENOTTY  Not  a  typewriter 

The  file  mentioned  in  an  ioctl  is  not  a  terminal  or  one  of  the  other  devices  to  which  these 
calls  apply. 

26  ETXTBSY  Text  file  busy 

An  attempt  to  execute  a  pure-procedure  program  which  is  currently  open  for  writing  (or 
reading!).  Also  an  attempt  to  open  for  writing  a  pure-procedure  program  that  is  being 
executed. 

27  EFBIQ  File  too  large 

The  size  of  a  file  exceeded  the  maximum  (about  10^  bytes). 

28  ENOSPC  No  space  left  on  device 

During  a  write  to  an  ordinary  file,  there  is  no  free  space  left  on  the  device. 
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29  ESPIPE  Illegal  seek 

An  htek  was  issued  to  a  pipe.  This  error  may  also  be  issued  for  other  non-seekable  dev¬ 
ices. 

30  EROFS  Read-only  file  system 

An  attempt  to  modify  a  file  or  directory  was  made  on  a  device  mounted  read-only. 

31  EMLINK  Too  many  links 

An  attempt  to  make  more  than  32767  hard  links  to  a  file. 

32  EPIPE  Broken  pipe 

A  write  on  a  pipe  or  socket  for  which  there  is  no  process  to  read  the  data.  This  condition 
normally  generates  a  signal;  the  error  is  returned  if  the  signal  is  ignored. 

33  EDOM  Math  argument 

The  argument  of  a  function  in  the  math  library  (as  described  in  section  3M)  is  out  of  the 
domain  of  the  function. 

34  ERANGE  Result  too  large 

The  value  of  a  function  in  the  math  library  (as  described  in  section  3M)  is  unrepresent¬ 
able  within  machine  precision. 

35  EWOULDBLOCK  Operation  would  block 

An  operation  which  would  cause  a  process  to  block  was  attempted  on  a  object  in  non- 
blocking  mode  (see  iocU{2)), 

36  EINPROGRESS  Operation  now  in  progress 

An  operation  which  takes  a  long  time  to  complete  (such  as  a  conntct{2))  was  attempted 
on  a  non-blocking  object  (see  t(ic^/(2)). 

37  EALREADY  Operation  already  in  progress 

An  operation  was  attempted  on  a  non-blocking  object  which  already  had  an  operation  in 
progress. 

38  ENOTSOCk  Socket  operation  on  non-socket 

Self-explanatory. 

39  EDESTADDRRkQ  Destination  address  required 

A  requited  address  was  omitted  from  an  operation  on  a  socket. 

40  EMSGSIZE  Message  too  long 

A  message  sent  on  a  socket  was  larger  than  the  internal  message  buffer. 

41  EPROTOTYPE  Protocol  wrong  type  for  socket 

A  protocol  was  specified  which  does  not  support  the  semantics  of  the  socket  type 
requested.  For  example  you  cannot  use  the  ARPA  Internet  UDP  protocol  with  type 
SOCK^STREAM. 

42  ENOPROTOOPT  Bad  protocol  option 

A  bad  option  was  specified  in  a  geteockopt{2)  or  9eteoek0pt{2)  call. 

43  EPROTOKOSUPPORT  Protocol  not  supported 

The  protocol  has  not  been  configured  into  the  system  or  no  implementation  for  it  exists. 

44  ESOCKTNOSUPPORT  Socket  type  not  supported 

The  support  for  the  socket  type  has  not  been  configured  into  the  system  or  no  implemen¬ 
tation  for  it  exists. 

45  EOPNOTSUPP  Operation  not  supported  on  socket 

For  example,  trying  to  accept  a  connection  on  a  datagram  socket. 

46  EPFNOSUPPORT  Protocol  family  not  supported 

The  protocol  family  has  not  been  configured  into  the  system  or  no  implementation  for  it 
exists. 
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47  EAFNO SUPPORT  Address  family  not  supported  by  protoeol  family 

An  address  incompatible  with  the  requested  protocol  was  used.  For  example,  you 
shouldn't  necessarily  expect  to  be  able  to  use  PUP  Internet  addresses  with  ARP  A  Inter¬ 
net  protocols. 

48  EADDRINUSE  Address  already  in  use 

Only  one  usage  of  each  address  is  normally  permitted. 

49  EADDRNOTAVAIL  Can’t  assign  requested  address 

Normally  results  from  an  attempt  to  create  a  socket  with  an  address  not  on  this  machine. 

50  ENETDOWN  Network  is  down 

A  socket  operation  encountered  a  dead  network. 

51  ENETUNREACH  Network  is  unreachable 

A  socket  operation  was  attempted  to  an  unreachable  network. 

52  ENETRESET  Network  dropped  connection  on  reset 

The  host  you  were  connected  to  crashed  and  rebooted. 

53  ECONNABORTED  Software  caused  connection  abort 

A  connection  abort  was  caused  internal  to  your  host  machine. 

54  ECONNRESET  Connection  reset  by  peer 

A  connection  was  forcibly  closed  by  a  peer.  This  normally  results  from  the  peer  execut¬ 
ing  a  Bhuidown(2)  call. 

55  ENOBUFS  No  buffer  space  available 

An  operation  on  a  socket  or  pipe  was  not  performed  because  the  system  lacked  sufficient 
buffer  space. 

56  EISCONN  Socket  is  already  connected 

A  connect  request  was  made  on  an  already  connected  socket;  or,  a  eendto  or  sendmsg 
request  on  a  connected  socket  specified  a  destination  other  than  the  connected  party. 

57  ENOTCONN  Socket  is  not  connected 

An  request  to  send  or  receive  data  was  disallowed  because  the  socket  is  not  connected. 

58  ESHUTDOWN  Can’t  send  after  socket  shutdown 

A  request  to  send  data  was  disallowed  because  the  socket  had  already  been  shut  down 
witk  a  previous  8hutdown{2)  call. 

59  unused 

60  ETIMEDOUT  Connection  timed  out 

A  connect  request  failed  because  the  connected  party  did  not  properly  respond  after  a 
period  of  time.  (The  timeout  period  is  dependent  on  the  communication  protocol.) 

61  ECONNREFUSED  Connection  refused 

No  connection  could  be  made  because  the  target  machine  actively  refused  it.  This  usu¬ 
ally  results  from  trying  to  connect  to  a  service  which  is  inactive  on  the  foreign  host. 

62  ELOOP  Too  many  levels  of  symbolic  links 

A  path  name  lookup  involved  more  than  8  embolic  links. 

63  ENAMETOOLONQ  File  name  too  long 

A  component  of  a  path  name  exceeded  255  characters,  or  an  entire  path  name  exceeded 
1023  characters. 

64  ENOTEMPTY  Directory  not  empty 

A  directory  with  entries  other  than  and  was  supplied  to  a  remove  directory  or 
rename  call. 
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DEFINITIONS 

Descriptor 

An  integer  assigned  by  the  system  when  a  file  is  referenced  by  open(2),  d\ip[2),  or  pipt{2)  or 
a  socket  is  referenced  by  eochtt{2)  or  6ocketpair{2)  which  uniquely  identifies  an  access  path 
to  that  file  or  socket  from  a  given  process  or  any  of  its  children. 

Directory 

A  directory  is  a  special  type  of  file  which  contains  entries  which  are  references  to  other  files. 
Directory  entries  are  called  links.  By  convention,  a  directory  contains  at  least  two  links,  . 
and  referred  to  as  dot  and  dot-dot  respectively.  Dot  refers  to  the  directory  itself  and  dot- 
dot  refers  to  its  parent  directory. 

Effective  User  Id,  Effective  Group  Id,  and  Access  Groups 

Access  to  system  resources  is  governed  by  three  values:  the  effective  user  ID,  the  effective 
group  ID,  and  the  group  access  list. 

The  effective  user  ID  and  effective  group  ID  are  initially  the  process’s  real  user  ID  and  real 
group  ID  respectively,  Either  may  be  modified  through  execution  of  a  set-user-ID  or  set- 
group-ID  file  (possibly  by  one  its  ancestors);  see  tztcvt(2y 

The  group  access  list  is  an  additional  set  of  group  ID’s  used  only  in  determining  resource 
accessibility.  Access  checks  are  performed  as  described  below  in  ’Tile  Access  Permissions”. 

File  Access  Permissions 

Every  file  in  the  file  system  has  a  set  of  access  permissions.  These  permissions  are  used  in 
determining  whether  a  process  may  perform  a  requested  operation  on  the  file  (such  as  open¬ 
ing  a  file  for  writing).  Access  permissions  are  established  at  the  time  a  file  is  created.  They 
may  be  changed  at  some  later  time  through  the  chmod(2)  call. 

File  access  is  broken  down  according  to  whether  a  file  may  be:  read,  written,  or  executed. 
Directory  files  use  the  execute  permission  to  control  if  the  directory  may  be  searched. 

File  access  permissions  are  interpreted  by  the  system  as  they  apply  to  three  different  classes 
of  users:  the  owner  of  the  file,  those  users  in  the  file’s  group,  anyone  else.  Every  file  has  an 
independent  set  of  access  permissions  for  each  of  these  classes.  When  an  access  check  is 
made,  the  system  decides  if  permission  should  be  granted  by  checking  the  access  informar 
tion  applicable  to  the  caller. 

Read,  ivrite,  and  execute/search  permissions  on  a  file  are  granted  to  a  process  if: 

The  process’s  effective  user  ID  is  that  of  the  super-user. 

The  process’s  effective  user  ID  matches  the  user  ID  of  the  owner  of  the  file  and  the  owner 
permissions  allow  the  access. 

The  process’s  effective  User  ID  does  not  match  the  user  ID  of  the  owner  of  the  file,  and 
either  the  process’s  effective  group  ID  matches  the  group  ID  of  the  file,  or  the  group  ID  of 
the  file  is  in  the  process’s  group  access  list,  and  the  group  permissions  allow  the  access. 

Neither  the  effective  user  ID  nor  effective  group  ID  and  group  access  list  of  the  process 
match  the  corresponding  user  ID  and  group  ID  of  the  file,  but  the  permissions  for  ’’other 
users”  allow  access. 

Otherwise,  permission  is  denied. 

File  Name 

Names  consisting  of  up  to  255  characters  may  be  used  to  name  an  ordinary  file,  special  file, 
or  directory. 

These  characters  may  be  selected  from  the  set  of  all  ASCII  character  excluding  0  (null)  and 
the  ASCII  code  for  /  (slash).  (The  parity  bit,  bit  S,  must  be  0.) 

Note  that  it  is  generally  unwise  to  use  |  or  }  as  part  of  file  names  because  of  the  special 
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meaning  attached  to  these  characters  by  the  shell. 

Parent  Process  ID 

A  new  process  is  created  by  a  currently  active  process;  see  fork{2).  The  parent  process  ID  of 
a  process  is  the  process  ID  of  its  creator. 

Path  Name 

A  path  name  is  a  nulLterminated  character  string  starting  with  an  optional  slash  (/),  fob 
lowed  by  zero  or  more  directory  names  separated  by  slashes,  optionally  followed  by  a  file 
name.  The  total  length  of  a  path  name  must  be  less  than  {PATHNAME^MAX}  characters. 

If  a  path  name  begins  with  a  slash,  the  path  search  begins  at  the  root  directory.  Otherwise, 
the  search  begins  from  the  current  working  directory.  A  slash  by  itself  names  the  root 
directory.  A  null  pathname  refers  to  the  current  directory. 

Process  Group  ID 

Each  active  process  is  a  member  of  a  process  group  that  is  identified  by  a  positive  integer 
called  the  process  group  ID.  This  is  the  process  ID  of  the  group  leader.  This  grouping  per* 
mils  the  signalling  of  related  processes  (see  killpg{2))  and  the  job  control  mechanisms  of 
ceA(l). 

Process  ID 

Each  active  process  in  the  system  is  uniquely  identified  by  a  positive  integer  called  a  process 
ID.  The  range  of  this  ID  is  from  0  to  30000. 

Real  User  ID  and  Real  Group  ID 

Each  user  on  the  system  is  identified  by  a  positive  integer  termed  the  real  user  ID. 

Each  user  is  also  a  member  of  one  or  more  groups.  One  of  these  groups  is  distinguished  from 
others  and  used  in  implementing  accounting  facilities.  The  positive  integer  corresponding  to 
this  distinguished  group  is  termed  the  real  group  ID. 

All  processes  have  a  real  user  ID  and  real  group  ID.  These  are  initialized  from  the 
equivalent  attributes  of  the  process  which  created  it. 

Root  Directory  and  Current  Working  Directory 

Each  process  has  associated  with  it  a  concept  of  a  root  directory  and  a  current  working 
directory  for  the  purpose  of  resolving  path  name  searches.  A  process's  root  directory  need 
not  be  the  root  directory  of  the  root  file  system. 

Sockets  and  Address  Families 

A  socket  is  an  endpoint  for  communication  between  processes.  Each  socket  has  queues  for 
sending  and  receiving  data. 

Sockets  are  typed  according  to  their  communications  properties.  These  properties  include 
whether  messages  sent  and  received  at  a  socket  require  the  name  of  the  partner,  whether 
communication  is  reliable,  the  format  used  in  naming  message  recipients,  etc. 

Each  instance  of  tke  system  supports  some  collection  of  socket  types;  consult  9ocket{2)  for 
more  information  about  the  types  available  and  their  properties. 

Each  ihstance  of  the  system  supports  some  number  of  sets  of  communications  protocols. 
Each  protocol  set  supports  addresses  of  a  certain  format.  An  Address  Family  is  the  set  of 
addresses  for  a  specific  group  of  protocols.  Each  socket  has  an  address  chosen  from  the 
address  family  in  which  the  socket  was  created. 

Special  Processes 

The  processes  with  a  process  ID's  of  0,  1,  and  2  are  special.  Process  0  is  the  scheduler.  Pro- 
cess  1  is  the  initialization  process  init,  and  is  the  ancestor  of  every  other  process  in  the  sys¬ 
tem.  It  is  used  to  control  the  process  structure.  Process  2  is  the  paging  daemon. 

Super-user 

A  process  is  recognized  as  a  super-user  process  and  is  granted  special  privileges  if  its 


6 


Last  change;  15  March  1984 


Sun  Release  1.1 


INTRO  (2) 


SYSTEM  CALLS 


INTRO  (2) 


o 

effective  user  ID  is 
Tty  Group  ID 

Each  active  process  can  be  a  member  of  a  terminal  group  that  is  identified  by  a  positive 
integer  called  the  tty  group  ID*  This  grouping  is  used  to  arbitrate  between  multiple  jobs 
contending  for  the  same  terminal;  see  caA(l),  and  tiy{4). 

SEE  ALSO 

intro(3),  perror(3) 
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ACCEPT(2) 


SYSTEM  CALLS 


ACCBPT(2) 


NAME 

accept  -  accept  a  connection  on  a  socket 
SYNOPSIS 

#include  <tya/typea.h> 

#lnclu(le  <ayt/tocket.h> 

na  s  accept(8,  addr^  addrlen) 

Int  na»  8| 

struct  sockaddr  ’^addri 
int  *addrlen| 


DESCRIPTION 

The  argument  s  is  a  socket  which  has  been  created  with  8ocket{2),  bound  to  an  address  with 
bind{2),  and  is  listening  for  connections  after  a  li8ten{2).  Accept  extracts  the  first  connection  on 
the  queue  of  pending  connections,  creates  a  new  socket  with  the  same  properties  of  s  and  allocates 
a  new  file  descriptor,  ns,  for  the  socket.  If  no  pending  connections  are  present  on  the  queue,  and 
the  socket  is  not  marked  as  non-blocking,  accept  blocks  the  caller  until  a  connection  is  present.  If 
the  socket  is  marked  non-blocking  and  no  pending  connections  are  present  on  the  queue,  accept 
returns  an  error  as  described  below.  The  accepted  socket,  ns,  is  used  to  read  and  write  data  to 
and  from  the  socket  which  connected  to  this  one;  it  is  not  used  to  accept  more  connections.  The 
original  socket  8  remains  open  for  accepting  further  connections. 

The  argument  addr  is  a  result  parameter  which  is  filled  in  with  the  address  of  the  connecting 
eptity,  as  known  to  the  communications  layer.  The  exact  format  of  the  addr  parameter  is  deter- 
n^fned  by  the  domain  in  which  the  communication  is  occurring.  The  addrlen  is  a  value-result 
parameter;  it  should  initially  contain  the  amount  of  space  pointed  to  by  addr;  on  return  it  will 
contain  the  actual  length  (in  bytes)  of  the  address  returned.  This  call  is  used  with  connection- 
based  socket  types,  currently  with  SOCK_STREAM. 

It  is  possible  to  select (2)  a  socket  for  the  purposes  of  doing  an  accept  by  selecting  it  for  read. 
RETURN  VALUE 

The  call  returns  -1  oa  error.  If  it  succeeds  it  returns  a  non-negative  integer  which  is  a  descriptor 
for  the  acceii^led  socket. 


ERRORS 

The  accept  will  fail  if: 


lEBADFl 

lENOTSOCK] 

lEOPNOTSUPP] 

(EFAULTl 

lEWOULDBLOCKj 


The  descriptor  is  invalid. 

The  descriptor  references  a  file,  not  a  socket. 

The  referenced  socket  is  not  of  type  SOCK^STREAM. 

The  addr  parameter  is  not  in  a  writable  part  of  the  user  address  space. 

The  socket  is  marked  non-blocking  and  no  connections  are  present  to  be 
accepted. 


SEE  ALSO 

bind(2),  connect(2),  listen(2),  8elect(2),  8ocket(2) 
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SYSTEM  CALLS 


ACCESS  (2) 


NAME 

access  -  determine  accessibility  of  file 
SYNOPSIS 

^Include  <syB/file«h> 

#define  R_OK  4  /*  test  for  read  permission  *( 

#define  W_OK  2  /*  test  for  write  permission  */ 

#define  X_OK  1  /*  test  for  execute  (search)  permission  */ 

#define  F_OK  0  /*  test  for  presence  of  file 

accessible  =  acce68(path»  mode) 
int  accessible; 
char  *path; 
int  mode; 

DESCRIPTION 

Acct88  checks  the  given  file  path  for  accessibility  according  to  mode,  which  is  an  inclusive  or  of 
the  bits  R_OK,  W_OK  and  XjOK.  Specifying  mode  as  F_OK  (i,e.  0)  tests  whether  the  direc* 
tories  leading  to  the  file  can  be  searched  and  the  file  exists. 

The  real  user  ID  and  the  group  access  list  (including  the  real  group  ID)  are  used  in  verifying  per¬ 
mission,  so  this  call  is  useful  to  set-UlD  programs. 

Notice  that  only  access  bits  are  checked.  A  directory  may  be  indicated  as  writable  by  access,  but 
an  attempt  to  open  it  for  writing  will  fail  (although  files  may  be  created  there);  a  file  may  look 
executable,  but  txeeve  will  fail  unless  it  is  in  proper  format. 

RETURN  VALUE 

If  path  cannot  be  found  or  if  any  of  the  desired  access  modes  would  not  be  granted,  then  a  -1 
value  is  returned;  otherwise  a  0  value  is  returned. 

ERRORS 

Access  to  the  file  is  denied  if  one  or  more  of  the  following  are  true: 

{ENOTDIR]  A  component  of  the  path  prefix  is  not  a  directory. 

|ENOENT|  The  argument  path  name  was  too  long. 

[ENOENTj  Read,  write,  or  execute  (search)  permission  is  requested  for  a  null  path  name  or 
the  named  file  does  not  exist. 

The  argument  contains  a  byte  with  the  high-order  bit  set. 

Too  many  symbolic  links  were  encountered  in  translating  the  pathname. 

Write  access  is  requested  for  a  file  on  a  read-only  file  system. 

Write  access  is  requested  for  a  pure  procedure  (shared  text)  file  that  is  being  exe¬ 
cuted. 

[EACCES]  Permission  bits  of  the  file  mode  do  not  permit  the  requested  access;  or  search 
permission  is  denied  on  a  component  of  the  path  prefix.  The  owner  of  a  file  has 

permission  checked  with  respect  to  the  '^owner’*  read,  write,  and  execute  mode 

bits,  members  of  the  file's  group  other  than  the  owner  have  permission  checked 
with  respect  to  the  ''group"  mode  bits,  and  all  others  have  permissions  checked 
with  respect  to  the  "other”  mode  bits. 

[EFAULT]  Path  points  outside  the  process's  allocated  address  space. 

SEE  ALSO 

chmod(2),  8tat(2) 
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[EPERM] 

|ELOOP| 

(EROFS) 

(ETXTBSY) 


ACCT(2) 


SYSTEM  CALLS 


ACCT(2) 


NAME 

acct  -  turn  accounting  on  or  off 

SYNOPSIS 

acct(flle) 

char 

DESCRIPTION 

The  syatenj  is  prepared  to  write  a  record  in  an  accounting  fUe  for  each  process  as  it  terminates. 
This  call,  with  a  null-terminated  string  naming  an  existing  file  as  argument,  turns  on  accounting; 
records  for  each  terminating  process  are  appended  to  JUt.  An  argument  of  0  causes  accounting  to 
be  turned  off. 

The  accounting  file  format  is  given  in  acc((5). 

This  call  is  permitted  only  to  the  super-user. 

NOTES 

Accounting  is  automatically  disabled  when  the  file  system  the  accounting  file  resides  on  runs  out 
of  space;  it  is  enabled  when  space  once  again  becomes  available. 

RETURN  VALUE 

On  error  -1  is  returned.  The  file  must  exist  and  the  call  may  be  exercised  only  by  the  super-user. 
It  is  erroneous  to  try  to  turn  on  accounting  when  it  b  already  on. 


ERRORS 

Acct  will  fail  if  one  of  the  following  is  true: 


[EPERMI 

(EPERM) 

(ENOTDIRl 

(ENOENT) 

[EISDIR] 

(EROFS) 

[EFAULTI 

[ELOOPj 

(EACCES) 

SEE  ALSO  , 

acct(5),  8a(8i 


The  caller  is  not  the  super-user. 

The  pathname  contains  a  character  with  the  high-order  bit  set. 

A  component  of  the  path  prefix  is  not  a  directory. 

The  named  file  does  not  exist. 

The  named  file  is  a  directory. 

The  named  file  resides  on  a  read-only  file  system. 

File  points  outside  the  process’s  allocated  address  space. 

Too  many  symbolic  links  were  encountered  in  translating  the  pathname. 
The  file  is  a  character  or  block  special  file. 


BUGS 

No  accounting  b  produced  for  programs  running  when  a  crash  occurs.  In  particular  nonterminat¬ 
ing  programs  are  never  accounted  for. 


10 


Last  change:  13  February  1983 


Sun  Release  1.1 


BIND(2) 


SYSTEM  CALLS 


BIND(2) 


NAME 

bind  -  bind  a  name  to  a  socket 
SYNOPSIS 

^include  <8yB/typee.h> 

^include  <sy8/80cket.h> 

b|ind(Bt  iiame»  namelen) 

i^ti) 

struct  soekaddr  ^namei 
namakni 

DESCRIPTION 

Bind  assigns  a  name  to  an  unnamed  socket.  When  a  socket  is  created  with  8ocket{2)  it  exists  in  a 
name  space  (address  family)  but  has  no  name  assigned.  Bind  requests  the  name,  be  assigned  to 
the  socket. 

NOTES 

Binding  a  name  in  the  UNIX  domain  creates  a  socket  in  the  file  system  which  must  be  deleted  by 
the  caller  when  it  is  no  longer  needed  (using  un/mA;(2)). 

The  rules  used  in  name  binding  vary  between  communication  domains.  Consult  the  manual 
entries  in  section  4  for  detailed  Information. 

RETURN  VALUE 

If  the  bind  is  successful^  n  0  value  is  returned.  A  return  value  of  -1  indicates  an  error^  which  is 
further  specified  in  the  global  errno. 

ERRORS 

The  bind  call  will  fail  if: 

[EBADF]  S  is  not  a  valid  descriptor. 

[ENOTSOCK]  5  is  not  a  socket. 

(EADDR  NOT  AVAIL]  The  specified  address  is  not  available  from  the  local  machine. 
(EADDRINUSE]  The  specified  address  is  already  in  use. 

[EINVAL]  The  socket  is  already  bound  to  an  address. 

[EACCES]  The  requested  address  is  protected^  and  the  current  user  has  inadequate 

permission  to  access  it. 

[EFAULT]  The  name  parameter  is  not  in  a  valid  part  of  the  user  address  space. 

SEE  ALSO 

connect(2),  U8ten(2),  socket(2),  getsockname(2) 

BUGS 

The  file  created  is  a  side-effect  of  the  current  implementation  and  will  not  be  created  in  future 
versions  of  the  Uf^DC  ipc  domain. 
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BRK(2) 


SYSTEM  CALLS 


BRK(2) 


NAME 

brk,  sbrk  -  change  data  segment  size 

SYNOPSIS 

eaddr_t  brk(addr) 
enddr.t  addr; 

eaddr.t  sbrk(iner) 
int  Ineri 

DESCRIPTION 

Brk  sets  the  system’s  idea  of  the  lowest  data  segment  location  not  used  by  the  program  (called  the 
break)  to  addr  (rounded  up  to  the  next  multiple  of  the  system’s  page  size).  Locations  greater 
than  addr  and  below  the  stack  pointer  are  not  in  the  address  space  and  will  thus  cause  a  memory 
violation  if  accessed. 

In  the  alternate  function  abrk,  iticr  more  bytes  are  added  to  the  program’s  data  space  amd  a 
pointer  to  the  start  of  the  new  area  is  returned. 

When  a  program  begins  execution  via  ezecve  the  break  is  set  at  the  highest  location  defined  by 
the  program  and  data  storage  areas.  Ordinarily,  therefore,  only  programs  with  growing  data 
areas  need  to  use  sbrk. 

The  getrlimit{2)  system  call  may  be  used  to  determine  the  maximum  permissible  size  of  the  data 
segment;  it  will  not  be  possible  to  set  the  break  beyond  the  rlimjnax  value  returned  from  a  call 
to  getrlimit,  e.g.  "etext  +  rlp-*rlim_max.”  (See  end(3)  for  the  definition  of  etezt.) 

RETURN  VALUE 

Zero  is  returned  if  the  brk  could  be  set;  -1  if  the  program  requests  more  memory  than  the  qrstem 
limit.  Sbrk  returns  -1  if  the  break  could  not  be  set. 

ERRORS 

Sbrk  will  fail  and  no  additional  memory  will  be  allocated  if  one  of  the  following  are  true: 
(ENOMEM)  The  limit,  as  set  by  «e(rh*>m'<(2),  was  exceeded. 

[ENOME\Q  The  maximum  possible  size  of  a  data  segment  (compiled  into  the  system)  was 
exceeded. 

(ENOMEM)  Insufficient  space  existed  in  the  swap  area  to  support  the  expansion. 

SEE  ALSO 

execve(2),  getrlimit(2),  malloc(3),  end(3) 

BUGS 

Setting  the  break  m^  fail  due  to  a  temporary  lack  of  swap  space.  It  is  not  possible  to  distinguish 
this  from  a  failure  caused  by  exceeding  the  maximum  size  of  the  data  segment  without  consulting 
getrlimit. 
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CHDm(2) 


SYSTEM  CALLS 


CHDIR(2) 


NAME 

chdir  -  change  cuirent  working  directoty 

SYNOPSIS 

chdir(path) 
char  *path| 


DESCRIPTION 

Path  13  the  pathname  of  a  directory,  Chdir  causes  this  directory  to  become  the  current  working 
directory,  the  starting  point  for  path  names  not  beginning  with 

In  order  for  a  directory  to  become  the  current  directory,  a  process  must  have  execute  (search) 
access  to  the  directory. 


RETURN  VALUE 

Upon  successful  completion,  a  value  of  0  is  returned. 
enrno  is  set  to  indicate  the  error. 


Otherwise,  a  value  of  -1  is  returned  and 


ERRORS 

Chdir  will  fail  and  the  current  working  directory  will  be  unchanged  if  one  or  more  of  the  following 
are  true: 


(ENOTDIRl 

[ENOENT] 

lENOENT) 

[EPERMl 

|EACCES| 

I^AULT} 

(ELOOPl 

SEE  ALSO 

chroot(2) 


A  component  of  the  pathname  is  not  a  directory. 

The  named  directory  does  not  exist. 

The  argument  path  name  was  too  long. 

The  argument  contains  a  byte  with  the  high-order  bit  set. 

Search  permission  is  denied  for  any  component  of  the  path  name. 

Path  points  outside  the  process’s  allocated  address  space. 

Too  many  symbolic  links  were  encountered  in  translating  the  pathname. 


o 


Sun  Release  1.1 


Last  change:  2  July  1983 


13 


CHM0D(2) 


SYSTEM  CALLS 


CHMOD(2) 


NAME 

chmod,  fchmod  -  change  mode  of  file 

SYNOPSIS 

chmod(path9  mode) 
char  *path$ 
int  mode; 

fchmod(fd|  mode) 
int  tdf  model 


DESCRIPTION 

The  file  whose  name  is  given  by  path  or  referenced  by  the  descriptor  fd  has  its  mode  changed  to 
mode.  Modes  are  constructed  by  or’ing  together  some  combination  of  the  following: 

04000  set  user  ID  on  execution 
02000  set  group  ID  on  execution 
01000  save  text  image  after  execution 
00400  read  by  owner 
00200  write  by  owner 

00100  execute  (search  on  directory)  by  owner 
00070  read,  write,  execute  (search)  by  group 
00007  read,  write,  execute  (search)  by  others 

If  an  executable  file  is  set  up  for  sharing  (this  is  the  default)  then  mode  1000  prevents  the  system 
from  abandoning  the  swap-space  image  of  the  program-text  portion  of  the  file  when  its  last  user 
terminates.  Ability  to  set  this  bit  is  restricted  to  the  super-user. 

Only  the  owner  of  a  file  (or  the  super-user)  may  change  the  mode. 

Writing  or  changing  the  owner  of  a  file  turns  off  the  set-user-id  and  set-group-id  bits.  This  makes 
the  system  somewhat  more  secure  by  protecting  set-user-id  (set-group-id)  files  from  remaining 
set-user-id  (set-group-id)  if  they  are  modified,  at  the  expense  of  a  degree  of  compatibility. 


RETURN  VALUE 

Upon  successful  completion,  a  value  of  0  is  returned.  Otherwise,  a  value  of  -1  is  returned  and 
errno  is  set  to  indicate  the  error, 

ERRORS 

Chmod  will  fail  and  the  file  mode  will  be  unchanged  if: 


(EPERM] 

[ENOTDIRl 

(ENOENTl 

(ENOENT) 

(EACCES) 

[EPERM] 

[EROFS] 

[EFAULT] 

[ELOOP] 


The  argument  contains  a  byte  with  the  high-order  bit  set. 

A  component  of  the  path  prefix  is  not  a  directory. 

The  pathname  was  too  long. 

The  named  file  does  not  exist. 

Search  permission  is  denied  on  a  component  of  the  path  prefix. 

The  effective  user  ID  does  not  match  the  owner  of  the  file  and  the  effective  user 
ID  is  not  the  super-user. 

The  named  file  resides  on  a  read-onty  file  system. 

Path  points  outside  the  process’s  allocated  address  space. 

Too  many  symbolic  links  were  encountered  in  translating  the  pathname. 


Fchmod  will  fail  if: 


(EBADFJ  The  descriptor  is  not  valid. 

[EINVAL]  Fd  refers  to  a  socket,  not  to  a  file. 

[EROFS]  The  file  resides  on  a  read-only  file  system. 
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CHM0D(2) 


SYSTEM  CALLS 


CHM0D(2) 


SEE  ALSO 

open(2),  chown(2) 
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CH0WN(2) 


SYSTEM  CALLS 


CHOWN(2) 


NAME 

cbown,  fchown  -  change  owner  and  group  of  a  file 
SYNOPSIS 

chown(pathf  owner^  group) 
char  *path| 

Int  owneri  groupi 

fchown(fd,  owner,  group) 
int  fd,  owner,  groups 

DESCRIPTION 

The  file  which  is  named  by  path  or  referenced  by  fd  has  its  owntr  and  group  changed  as  specified. 
Only  the  super-user  may  execute  this  call,  because  if  users  were  able  to  give  files  away,  they  could 
defeat  the  file-space  accounting  procedures. 

Chown  clears  the  set-user-id  and  sct-group-id  bits  on  the  file  to  prevent  accidental  creation  of  set^ 
user-id  and  set-group-id  programs  owned  by  the  super-user. 

Fchown  is  particularly  useful  when  used  in  conjunction  with  the  file  locking  primitives  (see 
flock{2)y 

Only  one  of  the  owner  and  group  id's  may  be  set  by  specifying  the  other  as  -1. 

RETURN  VALUE 

Zero  is  returned  if  the  operation  was  successful;  -1  is  returned  if  an  error  occurs,  with  a  more 
specific  error  code  being  placed  in  the  global  variable  errno. 

ERRORS 

C7hcu;n  will  fail  and  the  file  will  be  unchanged  if: 

[EINVALl  The  argument  path  docs  not  refer  to  a  file. 

[ENOTDIR]  A  component  of  the  path  prefix  is  not  a  directory, 

[ENOENT]  The  argument  pathname  is  too  long. 

(EPERM|  The  argument  contains  a  fcyte  with  the  high-order  bit  set. 

(ENOENT)  The  named  file  does  not  exist. 

[EACCES]  Search  permission  is  denied  on  a  component  of  the  path  prefix. 

[EPERM]  The  effective  user  ID  does  not  match  the  owner  of  the  file  and  the  effective  user 

ID  is  not  the  super-user. 

(EROFSj  The  named  file  resides  on  a  read-only  file  system. 

(EFAULT)  Path  points  outside  the  process's  allocated  address  space. 

[ELOOP]  Too  many  symbolic  links  were  encountered  in  translating  the  pathname. 

Fchown  will  fail  if: 

[EBADF]  Fd  does  not  refer  to  a  valid  descriptor. 

(EINVALj  Fd  refers  to  a  socket,  not  a  file. 

SEE  ALSO 

cbmod(2),  flock(2) 
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CHR00T(2) 


SYSTEM  CALLS 


CHR00T(2) 


NAME 

chroot  -  change  root  directory 

SYNOPSIS 

ehroot(<lirname) 
char  ^dirname) 

DESCRIPTION 

Dirname  is  the  address  of  the  pathname  of  a  directory,  terminated  by  a  null  byte.  Chroot  causes 
this  directory  to  become  the  root  directory,  the  starting  point  for  path  names  beginning  with  “/”• 
This  root  directory  setting  is  inherited  across  exeeve{2)  and  by  all  children  of  this  process  created 
with  fork(2)  calls. 

In  order  for  a  directory  to  become  the  root  directory  a  process  must  have  execute  (search)  access 
to  the  directory. 

This  call  is  restricted  to  the  super-user. 

RETURN  VALUE 

Upon  successful  completion,  a  value  of  0  is  returned.  Otherwise,  a  value  of  —1  is  returned  and 
errno  is  set  to  indicate  an  error. 

ERRORS 

Chroot  will  fail  and  the  root  directory  will  be  unchanged  if  one  or  more  of  the  following  are  true: 
[ENOTDIR]  A  component  of  the  path  name  is  not  a  directory. 

(ENOENTj  The  pathname  was  too  long. 

jEPERM]  The  argument  contains  a  byte  with  the  high-order  bit  set. 

(ENOENT]  The  named  directory  does  not  exist. 

jEACCES]  Search  permission  is  denied  for  any  component  of  the  path  name. 

(EFAULTj  Path  points  outside  the  process’s  allocated  address  space. 

|ELOOP]  Too  many  symbolic  links  were  encountered  in  translating  the  pathname. 

SEE  ALSO 

chdir(2) 
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NAME 

close  -  delete  a  descriptor 

SYNOPSIS 

eloae(d) 
int  d) 

DESCRIPTION 

The  close  call  deletes  a  descriptor  from  the  per-process  object  reference  table.  If  this  is  the  last 
reference  to  the  underlying  object,  then  it  wdl  be  deactivated.  For  example,  on  the  last  close  of  a 
file  the  current  seek  pointer  associated  with  the  file  is  lost;  on  the  last  close  of  a  eockei(2)  associ¬ 
ated  naming  information  and  queued  data  are  discarded;  on  the  last  close  of  a  file  bolding  an 
advisory  lock  the  lock  is  released,  see  Jlock{2)  for  further  information. 

A  close  of  all  of  a  process’s  descriptors  is  automatic  on  exit,  but  since  there  is  a  limit  on  the 
number  of  active  descriptors  per  process,  close  is  necessary  for  programs  which  deal  with  many 
descriptors. 

When  a  process  forks  (see  fork{2)),  all  descriptors  for  the  new  child  process  reference  the  same 
objects  as  they  did  in  the  parent  before  the  fork.  If  a  new  process  is  then  to  be  run  using 
exeeve[2),  the  process  would  normally  inherit  these  descriptors.  Most  of  the  descriptors  can  be 
rearranged  with  dtip2(2)  or  deleted  with  close  before  the  execve  is  attempted,  but  if  some  of  these 
descriptors  will  still  be  needed  if  the  execve  fails,  it  is  necessary  to  arrange  for  them  to  be  closed 
if  the  execve  succeeds.  For  this  reason,  the  call  “fcntl(d,  F_SETFD,  1)”  is  provided  which 
arranges  that  a  descriptor  will  be  closed  after  a  successful  execve;  the  call  “fcntl(d,  F_SETFD,  0)” 
restores  the  default,  which  is  to  not  close  the  descriptor. 

Close  unmaps  pages  mapped  through  this  file  descriptor. 

RETURN  VALUE 

Upon  successful  completion,  a  value  of  0  is  returned.  Otherwise,  a  value  of  -1  is  returned  and  the 
global  integer  variable  errno  is  set  to  indicate  the  error. 

ERRORS 

C^pse  will  fail  if: 

(EBADF]  D  is  not  an  active  descriptor. 

SEE  ALSO 

acccpt(2),  flock(2),  open(2),  pipe(2),  socket(2),  socketpair(2),  execve(2),  fcntl(2),  mmap(2),  mun- 
map(2) 
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NAME 

connect  -  initiate  a  connection  on  a  socket 
SYNOPSIS 

#inelude  <ay0/type8*h> 

#lQclude  <8yo/Bocket.h> 

connect(6,  namei  namelen) 
int  s| 

struct  Bockaddr  *name| 

Int  namelcni 

DESCRIPTION 

The  parametcf  r  is  a  socket.  If  it  is  of  type  SOCKJDGRAM,  then  this  call  permanently  specifies 
the  peer  to  which  datagrams  are  to  be  sent;  if  it  is  of  type  SOCK_STREAM,  then  this  call 
attempts  to  make  a  connection  to  another  socket.  The  other  socket  is  specified  by  name  which  is 
an  address  in  the  communications  space  of  the  socket.  Each  communications  space  interprets  the 
name  parameter  in  its  own  way. 

RETURN  VALUE 

If  the  connection  or  binding  succeeds,  then  0  is  returned.  Otherwise  a  -1  is  returned,  and  a  more 
specific  error  code  is  stored  in  errno. 

ERRORS 

The  call  fails  if: 

[EBADFj  S  is  not  a  valid  descriptor. 

(ENOTSOCKj  5  is  a  descriptor  for  a  file,  not  a  socket, 

|EADDRNOTAVAIL|  The  specified  address  is  not  available  on  this  machine. 

|EAFNOSUPPORTl  Addresses  in  the  specified  address  family  cannot  be  used  with  this  socket. 
[EISCONN]  The  socket  is  already  connected. 

[ETIMEDOUT]  Connection  establishment  timed  out  without  establishing  a  connection. 

[ECONNREFUSED]  The  attempt  to  connect  was  forcefully  rejected. 

[ENETUNREACH]  The  network  isn^t  reachable  from  this  host. 

[EADDRINUSE]  The  address  is  already  in  use. 

[EFAULT]  The  name  parameter  Bpecifles  an  area  outside  the  process  address  space. 

[EWOULDBLOCK]  The  socket  is  non-blocking  and  the  and  the  connection  cannot  be  com¬ 
pleted  immediately.  It  is  possible  to  $eteet{2)  the  socket  while  it  is  con¬ 
necting  by  selecting  it  for  writing. 

SEE  ALSO 

accept(2),  select(2),  socket(2),  get8ockname(2) 
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NAME 

creat  -  create  a  new  file 

SYNOPSIS 

creat(namei  mode) 
char  '''namei 

DESCRIPTION 

ThU  interface  li  obaoleted  by  open(2). 

Creat  creates  a  new  file  or  prepares  to  rewrite  an  existing  file  called  name,  given  as  the  address  of 
a  null-terminated  string.  If  the  file  did  not  exist,  it  is  given  mode  mode,  as  modified  by  the 
processes  mode  mask  (see  Also  see  cAmod(2)  for  the  construction  of  the  mode  argu¬ 

ment. 

If  the  file  did  exist,  its  mode  and  owner  remain  unchanged  but  it  is  truncated  to  0  length. 

The  file  is  also  opened  for  writing,  and  its  file  descriptor  is  returned. 


NOTES 

The  mode  given  is  arbitrary;  it  need  not  allow  writing.  This  feature  has  been  used  in  the  past  by 
programs  to  construct  a  simple  exclusive  locking  mechanism.  It  is  replaced  by  the  O.EXCL  open 
n^ode,  or  flock{2)  facilitity. 

RETURN  VALUE 

The  value  -1  b  returned  if  an  error  occurs.  Otherwise,  the  call  returns  a  non-negative  descriptor 
which  only  permits  writing. 


ERRORS 

Creat  will  fail  and  the  file  will  not  be  created  or  truncated  if  one  of  the  following  occur: 

[EPERM]  The  argument  contains  a  byte  with  the  high-order  bit  set. 

[ENOTDIR|  A  component  of  the  path  prefix  is  not  a  directory. 

[EACCES|  A  needed  directory  does  not  have  search  permission. 

[EACCES|  The  file  does  not  exist  and  the  directory  in  which  it  is  to  be  created  is  not  writ^ 
able. 


(EACCESI 

lEISDIR) 

lEMFILEj 

lEROFSj 

[ENXIOj 


The  file  exists,  but  it  is  unwritable. 

The  file  is  a  directory. 

There  are  already  too  many  files  open. 

The  named  file  resides  on  a  read-only  file  system. 

The  file  Is  a  character  special  or  block  special  file,  and  the  associated  device  does 
not  exist. 


[ETXTBSY)  The  file  is  a  pure  procedure  (shared  text)  file  that  is  being  executed. 
[EFAULT|  Name  points  outside  the  process’s  allocated  address  space. 

[ELOOPj  Too  many  symbolic  links  were  encountered  in  translating  the  pathname. 
(EOPNOTSUPP) 

The  file  was  a  socket  (not  currently  implemented). 


SEE  ALSO 

open  (2),  write(2),  close(2),  chmod(2),  umask(2) 
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NAME 

dup,  dup2  -  duplicate  a  descriptor 

SYNOPSIS 

newd  a  dup(oldd) 
int  newdf  oldd| 

dup2(oldd9  newd) 
int  oldd,  newd| 

DESCRIPTION 

Dup  duplicates  an  existing  object  descriptor.  The  argument  oldd  is  a  small  non-negative  integer 
index  in  the  per-process  descriptor  table.  The  value  must  be  less  than  the  size  of  the  table,  which 
is  returned  by  geidtabteeiZ€{2)*  The  new  descriptor  newd  returned  by  the  call  is  the  lowest  num¬ 
bered  descriptor  which  is  not  currently  in  use  by  the  process. 

The  object  referenced  by  the  descriptor  does  not  distinguish  between  references  using  oldd  and 
newd  in  any  way.  Thus  if  newd  and  oldd  are  duplicate  references  to  an  open  file,  rcarf(2),  write(2) 
and  lseek{2)  calls  all  move  a  single  pointer  into  the  file.  If  a  separate  pointer  into  the  file  is 
desired,  a  different  object  reference  to  the  file  must  be  obtained  by  issuing  an  additional  open (2) 
call. 

In  the  second  form  of  the  call,  the  value  of  newd  desired  is  specified.  If  this  descriptor  is  already 
in  use,  the  descriptor  is  first  deallocated  as  if  a  c/ose(2)  call  had  been  done  first. 

RETURN  VALUE 

The  value  -1  is  returned  if  an  error  occurs  in  either  call.  The  external  variable  trrno  indicates 
the  cause  of  the  error. 

ERRORS 

Dup  and  dup£  fail  if: 

[EBADF]  Oldd  or  newd  is  not  a  valid  active  descriptor 

[EMFILB]  Too  many  descriptors  are  active. 

SEE  ALSO 

accept(2),  open(2),  close(2),  pipe(2),  80cket(2),  80cketpair(2),  getdtablesize(2) 
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NAME 

execve  -  execute  a  file 
SYNOPSIS 

execve(name9  argv^  envp) 
char  *name,  ^argvD,  *envp[]| 

DESCRIPTION 

Extcvt  transforms  the  calling  process  into  a  new  process.  The  new  process  is  constructed  from  an 
ordinaiy  file  called  the  neu;  process  file.  This  file  is  either  an  executable  object  file,  or  a  file  of 
data  for  an  interpreter.  An  executable  object  file  consists  of  an  identifying  header,  followed  by 
pages  of  data  representing  the  initial  program  (text)  and  initialized  data  pages.  Additional  pages 
may  be  specified  by  the  header  to  be  initialize  with  zero  data.  See  u.ou^(5). 

An  interpreter  file  begins  with  a  line  of  the  form  mlerprclcr'*;  When  an  interpreter  file  is 
exeeve  *d,  the  system  czccvc’s  the  specified  interpreter,  giving  it  the  name  of  the  originally  exec’d 
file  as  an  argument,  shifting  over  the  rest  of  the  original  arguments. 

There  can  be  no  return  from  a  successful  exeeve  because  the  calling  core  image  is  lost.  This  is  the 
mechanism  whereby  different  process  images  become  active. 

The  argumefit  at'ffv  is  an  array  of  character  pointers  to  null-terminated  character  strings.  These 
strings  constitute  the  argument  list  to  be  m^e  available  to  the  new  process.  By  convention,  at 
least  one  argument  must  be  present  in  this  array,  and  the  first  element  of  this  array  should  be  the 
name  of  the  executed  program  (i.e.  the  last  component  of  name). 

The  argument  cnt;p  is  also  an  array  of  character  pointers  to  nuIL terminated  strings.  These  strings 
pass  information  to  the  new  process  which  are  not  directly  arguments  to  the  command,  see 
environ(5). 

Descriptors  open  in  the  calling  process  remain  open  in  the  new  process,  except  for  those  for  which 
the  close-on-exec  flag  is  set;  see  elose(2).  Descriptors  which  remain  open  are  unaffected  by  exeeve. 

Ignored  signals  remain  ignored  across  an  exeeve,  but  signals  that  are  caught  are  reset  to  their 
default  values.  The  signal  stack  is  reset  to  be  undefined;  see  9%Qvec{2)  for  more  information. 

Each  process  has  a  real  user  ID  and  group  ID  and  an  effective  user  ID  and  group  ID.  The  real  ID 
identifies  the  person  using  the  system;  the  effective  ID  determines  his  access  privileges.  Exeeve 
changes  the  effective  user  and  group  ID  to  the  owner  of  the  executed  file  if  the  file  has  the  ^'setp 
user- ID”  or  ^set^group-ID”  modes.  The  real  user  ID  is  not  affected. 

The  new  process  also  inherits  the  following  attributes  from  the  calling  process: 


protess  IB 

see  Qetpid(2) 

parent  process  ID 

see  Qetppid{2) 

process  group  ID 

see  getpgrp{2) 

access  groups 

see  getgroupe{2) 

working  directory 

see  cAdtr(2) 

root  directory 

see  chroot{i) 

control  terminal 

see  l^|if(4) 

resource  usages 

see  geirusagel^) 

interval  timers 

see  getitimer{2) 

resource  limits 

see  getrlimit{2) 

file  mode  mask 

see  uma8l^2) 

signal  mask 

see  eigvee{2) 

When  the  executed  program  begins,  it  is  called  as  follows: 

mam(argc,  argv,  envp) 
int  arge; 

char  **argv,  **envp; 
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where  argc  is  the  number  of  elements  in  argv  (the  “arg  count’*)  and  argv  is  the  array  of  character 
pointers  to  the  arguments  themselves. 

Envp  is  a  pointer  to  an  array  of  strings  that  constitute  the  environment  of  the  process.  A  pointer 
to  this  array  is  also  stored  in  the  global  variable  **environ”.  Each  string  consists  of  a  name,  an 
and  a  nulLterminated  value.  The  array  of  pointers  is  terminated  by  a  null  pointer.  The 
shell  sA(l)  passes  an  environment  entry  for  each  global  shell  variable  defined  when  the  program  is 
called.  See  entn>on(5)  for  some  conventionally  used  names. 

RETURN  VALUE 

If  execve  returns  to  the  calling  process  an  error  has  occurred;  the  return  value  will  be  -1  and  the 
global  variable  errno  will  contain  an  error  code. 


ERRORS 

Exeeve  will  fail  and  return  to  the  calling  process  if  one  or  more  of  the  following  are  true: 


(ENOENT) 

[ENOTDIRl 

[EACCESl 

(EACCESl 

(EACCESj 

(ENOEXEC) 

(ETXTBSYI 


One  or  more  components  of  the  new  process  file’s  path  name  do  not  exist. 

A  component  of  the  new  process  file  is  not  a  directory. 

Search  permission  is  denied  for  a  directory  listed  in  the  new  process  file’s  path 
prefix* 

The  new  process  file  is  not  an  ordinary  file. 

The  new  process  file  mode  denies  execute  permission. 

The  new  process  file  has  the  appropriate  access  permission,  but  has  an  invalid 
magic  number  in  its  header. 

The  new  process  file  is  a  pure  procedure  (shared  text)  file  that  is  currently  open 
for  writing  or  reading  by  some  process. 


[BNOMEM]  The  new  process  requires  more  virtual  memory  than  is  allowed  by  the  imposed 
maximum  {geirlimii{2)). 

[E2BIG]  The  number  of  bytes  In  the  new  process’s  argument  list  is  larger  than  the 

system-imposed  limit  of  {ARG_MAX}  bytes. 


[EFAULT]  The  new  process  file  is  not  as  long  as  indicated  by  the  size  values  in  its  header. 
(EFAULT]  Path,  argv,  or  envp  point  to  an  illegal  address. 

CAVEATS 

If  a  program  is  setuid  to  &  non-super-user »  but  is  executed  when  the  real  uid  is  ’’root”,  then  the 
program  has  the  powers  of  a  super-user  as  well. 


SEE  ALSO 

exit(2),  fork(2),  execl(3),  environ(5) 
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NAME 

_exit  -  terminate  a  process 

SYNOPSIS 

jexlt(atatus) 
int  atatus} 

DESCRIPTION 

jtnt  terminates  a  process  with  the  following  consequences: 

All  of  the  descriptors  open  in  the  calling  process  are  closed. 

If  the  parent  process  of  the  calling  process  is  executing  a  wait  or  is  interested  in  the  SIGCHLD 
signal,  then  it  is  notified  of  the  calling  process’s  termination  and  the  Iow>order  eight  bits  of  atafua 
are  made  available  to  it;  see  u;atl(2).  The  low-order  8  bits  of  atatua  are  available  to  the  parent 
process. 

The  parent  process  ib  of  aU  of  the  calling  process's  existing  child  processes  are  also  set  to  1.  This 
means  that  the  initialization  process  (see  mfro(2))  inherits  each  of  these  processes  as  well. 

Most  C  programs  will  call  the  library  routine  eat<(3)  which  performs  cleanup  actions  in  the  stan¬ 
dard  i/o  library  before  calling  _exit. 

RETURN  VALUE 

This  call  never  returns. 

SEE  ALSO 

fork(2),  wait(2),  exit(3) 
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NAME 

fcDtl  -  file  control 


SYNOPSIS 

#include  <fciitLh> 

res  s  fcntl(fd,  emd|  arg) 
int  resi 

Int  fd)  cnKlf  arg| 


DESCRIPTION 

Fcnil  provides  for  control  over  descriptors.  The  argument  fd  is  a  descriptor  to  be  operated  on  by 
cmd  as  follows: 


F  DUPFD 


F^GETFD 

F_SETFD 

F^GETFL 

F_SETFL 

F.GETOWN 

F.SETOWN 


Return  a  new  descriptor  as  follows: 

Lowest  numbered  available  descriptor  greater  than  or  equal  to  arg. 

Same  object  references  as  the  original  descriptor. 

New  descriptor  shares  the  same  file  pointer  if  the  object  was  a  file. 

Same  access  mode  (read,  write  or  read/write). 

Same  file  status  flags  (i.o.,  both  file  descriptors  share  the  same  file  status  flags). 

The  close-on^exec  flag  associated  with  the  new  file  descriptor  is  set  to  remain 
open  across  execve{2)  system  calls. 

Get  the  close^Q^exec  flag  associated  with  the  file  descriptor  fd.  If  the  low'^order 
bit  is  0,  the  file  will  remain  open  across  exec,  otherwise  the  file  will  be  closed 
upon  execution  of  ezee. 

Set  the  close-on-exec  flag  associated  with  fd  to  the  low  order  bit  of  (0  or  1  as 
above). 

Get  descriptor  status  flags,  see  fcntl{b)  for  their  definitions. 

Set  descriptor  status  flags,  see  /cn^/(5)  for  their  definitions. 

Get  the  process  ID  or  process  group  currently  receiving  SIGIO  and  SIGURG  sig¬ 
nals;  process  groups  are  returned  as  negative  values. 

Set  the  process  or  process  group  to  receive  SIGIO  and  SIGURG  signals;  process 
groups  are  specified  by  supplying  arg  as  negative,  otherwise  arg  is  interpreted  as 
a  process  ID. 


The  SIGIO  facilities  are  enabled  by  setting  the  FASYNC  flag  with  F_SETFL. 


RETURN  VALUE 

Upon  successful  completion,  the  value  returned  depends  on  cmd  as  follows: 


PJ)UPFtl 

F.GETFp 

f^getfL 

F.GETOWN 

other 


A  new  file  descriptor. 

Value  of  flag  (only  the  Iow<order  bit  is  defined). 
Value  of  flags. 

Value  of  file  descriptor  owner. 

Value  other  than  -1. 


Otherwise,  a  value  of  -1  is  returned  and  trrno  is  set  to  indicate  the  error. 

ERRORS 

Fcnil  will  fail  if  one  or  more  of  the  following  are  true: 

|EBADF]  Fildee  is  not  a  valid  open  file  descriptor. 

(EMFILE]  Cmd  is  F_DUPFD  and  the  maximum  allowed  number  of  file  descriptors  are 

currently  open. 
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[EINVAL]  Cmd  is  F_PUPFD  and  arg  is  negative  or  greater  the  maximum  allowable  number 
(see  getdtableaize{2)). 


SEE  ALSO 

close(2),  execve(2),  getdtablesize(2),  open(2),  8igvec(2) 
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NAME 

flock  -  apply  or  remove  an  advisory  lock  on  an  open  file 
SYNOPSIS 

#ti:clud«  <By6/flIe.h> 

#deflno  LOCK_SH  1  /*  abared  lock  */ 

#deflne  LOCK_EX  2  /•  exclusive  lock  */ 

#defloe  LOCK.NB  4  /*  don’t  block  when  locking  */ 

#define  LOCkIuN  8  /*  unlock  */ 

^ock(fd,  operation) 
l|^t  fd,  operation] 

DESCRIPTION 

Flock  applies  or  removes  an  advisory  lock  on  the  file  associated  with  the  file  descriptor  fd.  A  lock 
is  applied  by  specifying  an  operation  parameter  which  is  the  inclusive  or  of  LOCK_SH  or 
LOCK_FX  and,  possibly,  LOCK_NB.  To  unlock  an  existing  lock  operation  should  be 
LOCK_UN. 

Advisory  locks  allow  cooperating  processes  to  perform  consistent  operations  on  files,  but  do  not 
guarantee  consistency  (i.e.  processes  may  still  access  files  without  using  advisory  locks  possibly 
resulting  in  inconsistencies). 

The  locking  mechanism  allows  two  types  of  locks:  shared  locks  and  exclusive  locks.  At  any  time 
multiple  shared  locks  may  be  applied  to  a  file,  but  at  no  time  are  multiple  exclusive,  or  both 
shared  and  exclusive,  locks  allowed  simultaneously  on  a  file. 

A  shared  lock  may  be  upgraded  to  an  exclusive  lock,  and  vice  versa,  simply  by  specifying  the 
appropriate  lock  type;  this  results  in  the  previous  lock  being  released  and  the  new  lock  applied 
(possibly  after  other  processes  have  gained  and  released  the  lock). 

Requesting  a  lock  on  an  object  which  is  already  locked  normally  causes  the  caller  to  blocked  until 
the  lock  may  be  acquired.  If  LOCK_NB  is  included  in  operation,  then  this  will  not  happen; 
instead  the  call  will  fail  and  the  error  EWOULDBLOCK  will  be  returned. 

NOTES 

Locks  are  on  flies,  not  file  descriptors.  That  is,  file  descriptors  duplicated  through  dup{2)  or 
/orA;(2)  do  not  result  in  multiple  instances  of  a  lock,  but  rather  multiple  references  to  a  single 
lock.  If  a  process  holding  a  lock  on  a  file  forks  and  the  child  explicitly  unlocks  the  file,  the  parent 
will  lose  its  lock. 

Processes  blocked  awaiting  a  lock  may  be  awakened  by  signals. 

RETURN  VALUE 

Zero  is  returned  if  the  operation  was  successful;  on  an  error  a  -1  is  returned  and  an  error  code  is 
left  in  the  global  location  errno, 

ERRORS 

The  flock  call  fails  if: 

(EWOULDBLOCK) 

(EBADF) 

[einvalI 

SEE  ALSO 

opeQ(2),  cIo8e(2),  dup(2)^  execve(2),  fork(2) 


The  file  is  locked  and  the  LOCK^NB  option  was  specified. 
The  argument  fd  is  an  invalid  descriptor. 

The  argument  fd  refers  to  an  object  other  than  a  file. 
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F0RK(2) 


SYSTEM  CALLS 


FORK(2) 


NAME 

fork  -  create  a  new  process 
SYNOPSIS 

pld  5=s  forkQ 

Int  pld| 

DESCRIPTION 

Fork  causes  creation  of  a  new  process.  The  new  process  (child  process)  is  an  exact  copy  of  the 
calling  process  except  for  the  following: 

The  child  process  has  a  unique  process  ID. 

The  child  process  has  a  different  parent  process  ID  (i.e.,  the  process  ID  of  the  parent  prcv 
cess). 

The  child  process  has  its  own  copy  of  the  parent’s  descriptors.  These  descriptors  reference 
the  same  underlying  objects,  so  that,  for  instance,  file  pointers  in  file  objects  are  shared 
between  the  child  and  the  parent,  so  that  a  Ueek{2)  on  a  descriptor  in  the  child  process  can 
affect  a  subsequent  read  or  write  by  the  parent.  This  descriptor  copying  is  also  used  by  the 
shell  to  establish  standard  input  and  output  for  newly  created  processes  as  well  as  to  set  up 
pipes. 


The  child  processes  resource  utilizations  are  set  to  0;  see  8etrHmit{2). 

RETURN  VALUE 

Upon  successful  completion,  fork  returns  a  value  of  0  to  the  child  process  and  returns  the  process 
ID  of  the  child  process  to  the  parent  process.  Otherwise,  a  value  of  -1  is  returned  to  the  parent 
process,  no  child  process  is  created,  and  the  global  variable  errno  is  set  to  indicate  the  error. 

ERRORS 

Fork  will  fail  and  no  child  process  will  be  created  if  one  or  more  of  the  following  are  true: 

(EAGAINj  The  system-imposed  limit  {PROC_MAX}  on  the  total  number  of  processes 
under  execution  would  be  exceeded. 

[EAGAIN|  The  system-imposed  limit  {KID^MAX}  on  the  total  number  of  processes  under 
execution  by  a  single  user  would  be  exceeded. 

SEE  ALSO 

execve(2),  wait(2) 
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FSYNC(2) 


SYSTEM  CALLS 


FSYNC(2) 


NAME 

fsync  -  synchronize  a  file’s  in>core  state  with  that  on  disk 

SYNOPSIS 

fsyne(fd) 

intfd) 

DESCRIPTION 

Fst/ne  causes  all  modified  data  and  attributes  of  fd  to  be  moved  to  a  permanent  storage  device:  all 
in-core  modified  copies  of  buffers  for  the  associated  file  have  been  written  to  a  disk  when  the  call 
returns.  (Note  that  this  is  different  than  «yne(2)  which  schedules  disk-io  for  all  files  (as  though  an 
fiync  had  been  done  on  all  files)  but  returns  before  the  i/o  completes.) 

Feync  should  be  used  by  programs  which  require  a  file  to  be  in  a  known  state;  for  example  in 
building  a  simple  transaction  facility. 

RETURN  VALUE 

A  0  value  is  returned  on  success.  A  -1  value  indicates  an  error. 

ERRORS 

The  feyne  fails  if: 

I^ADF}  Fi  is  not  a  valid  descriptor. 

I^INVAL]  Fd  refers  to  a  socket,  not  to  a  file. 

SEE  ALSO 

sync(2),  sync(8),  cron(8) 

BUGS 

The  current  implementation  of  this  call  is  expensive  for  targe  files. 


o 
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GETDTABLESIZE(2) 


SYSTEM  CALLS 


GETDTABLESIZE(2) 


NAME 

getdtablesize  -  get  descriptor  table  size 
SYNOPSIS 

nde  =  getdt&bleslseO 
int  nda| 

DESCRIPTION 

Each  process  has  a  fixed  size  descriptor  table  which  is  guaranteed  to  have  at  least  20  slots.  The 
entries  in  the  descriptor  table  are  numbered  with  small  integers  starting  at  0.  The  call  getdta- 
biesize  returns  the  size  of  this  table. 

SEE  ALSO 

close(2),  dup(2)i  open (2) 
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GETGID(2) 


SYSTEM  CALLS 


GETGID(2) 


getgid,  getegid  -  get  group  identity 

SYNOPSIS 

gld  =  getgldQ 
lut  gld} 

egld  =s  getegld() 

Int  egld} 

DESCRIPTION 

Getgii  returns  the  real  group  ID  of  the  current  process,  getegid  the  effective  group  ED. 

The  real  group  ID  b  specified  at  login  time. 

The  effective  group  ID  b  more  transient,  and  determines  additional  access  permission  during  exe¬ 
cution  of  a  "set-group-ID"  process,  and  it  b  for  such  processes  that  getgid  is  most  useful. 

SEE  ALSO 

getuid(2),  Betregid(2),  8etgid(3C) 


o 


o 
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GETGR0UPS(2) 


SYSTEM  CALLS 


GETGROUPS(2) 


NAME 

getgroups  -  get  group  access  list 
SYNOPSIS 

#include  <sya/param.h> 

ngroupa  =  getgroup8(nt  &gldset) 
int  ngroupa; 

Int  Uf  "^gldaet^ 

DESCRIPTION 

Get  group  8  gets  the  current  group  access  list  of  the  user  process  and  stores  it  in  the  array  gidset. 
The  parameter  n  indicates  the  number  of  entries  which  may  be  placed  in  gidstt  and  get  groups 
returns  the  actual  number  of  entries  placed  in  the  gideet  array.  No  more  than  NGRPS,  as  defined 
in  <8y8fparam,k>f  will  ever  be  returned. 

RETURN  VALUE 

A  return  value  of  greater  than  zero  indicates  the  number  of  entries  placed  in  the  gidset  array.  A 
return  value  of  -1  indicates  that  an  error  occurred,  and  the  error  code  is  stored  in  the  global  vari¬ 
able  errnOi 

ERRORS 

The  possible  errors  for  get  group  are: 

|EFAULT|  The  arguments  ngroups  or  gidset  specify  invalid  addresses. 

SEE  ALSp 

se|gToups(2),  initgroup8(3) 
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GETH0STID(2) 


SYSTEM  CALLS 


GETH0STID(2) 


NAME 

gethostid  -  get  unique  identifier  of  current  host 
SYNOPSIS 

hostid  —  gethostldO 
Int  hostid] 

DESCRIPTION 

Gethoetid  returns  the  32-bit  identifier  for  the  current  host,  which  is  unique  across  all  hosts. 

SEE  ALSO 

bostid(l) 


o 
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GETH0STNAME(2) 


SYSTEM  CALLS 


GETH0STNAME(2) 


NAME 

get  hostname,  sethostname  ~  get /set  name  of  current  host 
SYNOPSIS 

getho5tname(nainei  namelen) 
char  *name; 
int  nameleni 

Bethostname(namef  namelen) 
char  '*‘name| 
int  namelen; 

DESCRIPTION 

Geihosinamt  returns  the  standard  host  name  for  the  current  processor,  as  previously  set  by 
eeihosinamt.  The  parameter  namtltn  specifies  the  size  of  the  namt  array»  The  returned  name  is 
null-terminated  unless  insufl^cient  space  is  provided* 

SeihoBinamt  sets  the  name  of  the  host  machine  to  be  name,  which  has  length  namelen.  This  call 
is  restricted  to  the  super-user  and  is  normally  used  only  when  the  system  is  bootstrapped. 

RETURN  VALUE 

If  the  call  succeeds  a  value  of  0  is  returned.  If  the  call  fails,  then  a  value  of  -1  is  returned  and  an 
error  code  is  placed  int  the  global  location  errno. 

ERRORS 

The  following  errors  may  be  returned  by  these  calls: 

[EPAULT]  The  namt  or  namelen  parameter  gave  an  Invalid  address. 

(EPERM]  The  caller  was  not  the  super-user. 

SEE  ALSO 

gethostid(2) 

BUGS 

Host  names  are  limited  to  255  characters. 
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GETITIMER(2) 


SYSTEM  CALLS 


GETITIMER(2) 


NAME 

getitimer,  seti timer  -  get/set  value  of  interval  timer 
SYNOPSIS 

#Inelude  <By8/tlme»h> 

^define  IXIMER_R£AL  0  real  time  intervals 

#defiiie  ITIMER_yiRTUAL  1  /*  virtual  time  intervals  */ 

^define  ITIMER^PROF  S  /♦  user  and  system  virtual  time  */ 

getitimer(whleh|  value) 
int  whichi 

struct  Itimerval  *value| 

Betltimer(which|  valuCf  ovalue) 
int  whiehi 

struct  itimerval  ^valuei  ’^‘ovaluei 

DESCRIPTION 

The  system  provides  each  process  with  three  interval  timers,  defined  in  <8y8lHme.h>,  The  geii- 
iimtr  call  returns  the  current  value  for  the  timer  specified  in  which,  while  the  sttiiiimer  call  sets 
the  value  of  a  timer  (optionally  returning  the  previous  value  of  the  timer). 

A  timer  value  is  defined  by  the  itimerval  structure: 
struct  itimerval  { 

struct  timeval  itjnterval;  /*  timer  interval  ♦/ 

struct  timeval  it_value;  /♦  current  value  */ 

}> 

If  ii^valnt  is  non-zero,  it  indicates  the  time  to  the  next  timer  expiration.  If  itjintervai  is  non-zero, 
it  specifies  a  value  to  be  used  in  reloading  iijualut  when  the  timer  expires.  Setting  iijualuc  to  0 
disables  a  timer.  Setting  itjinierval  to  0  causes  a  timer  to  be  disabled  after  its  next  expiration 
(assuming  Upvalue  is  non-zero). 

Time  values  smaller  than  the  resolution  of  the  system  clock  are  rounded  up  to  this  resolution. 

The  ITIMERJIEAL  timer  decrements  in  real  time,  A  SIGALRM  signal  is  delivered  when  this 
timer  expires. 

The  ITI\&R_yiRTUAL  timer  decrements  in  process  virtual  time.  It  runs  only  when  the  process 
is  executing.  A  SIGVTALRM  signal  is  delivered  when  it  expires. 

The  ITIMEkjPROF  timer  decrements  both  in  process  virtual  time  and  when  the  system  is  run¬ 
ning  on  behalf  of  the  process.  It  is  designed  to  be  used  by  interpreters  in  statistically  profiling  the 
execution  of  interpreted  programs.  Each  time  the  ITIMERJ^ROF  timer  expires,  the  SIGPROF 
signal  is  delivered.  Because  this  signal  may  interrupt  tn-progress  system  calls,  programs  using  this 
timer  must  be  prepared  to  restart  interrupted  system  calls. 

NOTES 

Three  macros  for  manipulating  time  values  are  defined  in  <sys/hmc.A>.  Timcrclear  sets  a  time 
value  to  zero,  timermet  tests  if  a  time  value  is  non-zero,  and  timercmp  compares  two  time  values 
(beware  that  >«=  aiid.<=  do  not  work  with  this  macro). 

RETURN  VALUE 

If  the  calls  succeed,  a  value  of  0  is  returned.  If  an  error  occurs,  the  value  -1  is  returned,  and  a 
more  precise  error  code  is  placed  in  the  global  variable  errno. 

ERRORS ' 

The  possible  errors  are: 

[E^AULTj  The  value  structure  specified  a  bad  address. 
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GETITIMER(2) 


SYSTEM  CALLS 


GETITIMER(2) 


c 


[EINVALj  A  value  structure  specified  a  time  was  too  large  to  be  handled. 
SEE  ALSO 

sigvec(2),  gettimeofday(2) 


c 
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GETPAGESIZE(2) 


SYSTEM  CALLS 


GETPAGESIZE(2) 


NAME 

getpagesize  -  get  system  page  size 
SYNOPSIS 

page&lse  =  getpageslzeO 
istt  ptxgeolze$ 

DESCRIPTION 

Getpagesize  returns  the  number  of  bytes  in  a  page.  Page  granularity  is  the  granularity  of  many  of 
the  memory  management  calls. 

The  page  size  is  a  system  page  size  and  may  not  be  the  same  as  the  underlying  hardware  page 
size. 

SEE  ALSO 

8brk(2),  page8ize(l) 
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GETPEERNAME(2) 


SYSTEM  CALLS 


GETPEEBNAME(2) 


c 


NAME 

getpeername  -  get  name  of  connected  peer 
SYNOPSIS 

Betpeername(s,  name,  namelen) 

Int  B| 

etruet  soekaddr  *namef 
Int  ^namelen} 


DESCRIPTION 

Getpeername  returns  the  name  of  the  peer  connected  to  socket  ».  The  namelen  parameter  should 
be  initialized  to  indicate  the  amount  of  space  pointed  to  by  name.  On  return  it  contains  the 
actual  size  of  the  name  returned  (in  bytes). 

DIAGNOSTICS 

A  0  is  returned  if  the  call  succeeds,  -1  if  it  fails. 

ERRORS 

The  call  succeeds  unless: 


(EBADF) 

(ENOTSOCK) 

(ENOTCONNj 

[ENOBUFS] 

lEFAULT] 


The  argument  » is  not  a  valid  descriptor. 

The  argument  « is  a  file,  not  a  socket. 

The  socket  is  not  connected. 

Insufficient  resources  were  available  in  the  system  to  perform  the  operation. 

The  nome  parameter  points  to  memory  not  in  a  valid  part  of  the  process  address 
space. 


SEE  ALSO 

bind(2),  socket(2),  get80ckname(2) 

BUGS 

Names  bound  to  sockets  in  the  UNIX  domain  are  inaccessible;  getpeername  returns  a  zero  length 
name. 
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GETPGRP(2) 


SYSTEM  CALLS 


GETPGRP(2) 


NAME 

getpgrp  -  get  process  group 
SYNOPSIS 

pgrp  =  getpgrp(pid) 

Int  prgp} 

Int  pld| 

DESCRIPTION 

The  process  group  of  the  specified  process  is  returned  by  getpgrp.  If  pid  is  zero,  then  the  call 
applies  to  the  current  process. 

Process  groups  are  used  for  distribution  of  signals,  and  by  terminals  to  arbitrate  requests  for  their 
input:  processes  vhich  have  the  same  process  group  as  the  terminal  are  foreground  and  may  read, 
while  others  will  block  with  a  signal  if  they  attempt  to  read. 

This  call  is  thus  used  by  programs  such  as  csA(l)  to  create  process  groups  in  implementing  job 
control.  The  TIOCGPGRP  and  TIOCSPGRP  c^ls  described  in  ity(4)  are  used  to  get/set  the 
process  group  of  the  control  terminal. 

SEE  ALSO 

8etpgrp(2),  getuid(2),  tty(4) 


o 
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GETPID(2) 


SYSTEM  CALLS 


GETPID(2) 


NAME 

getpid,  getppid  -  get  process  identification 

SYNOPSIS 

pld  =  getpidQ 
loDg  pid| 

ppid  =s  getppldO 
long  ppidi 

DESCRIPTION 

Geipid  returns  the  process  ID  of  the  current  process.  Most  often  it  is  used  with  the  host  identifier 
g€tko8tid{2)  to  generate  uniquely-named  temporary  files. 

Getppid  returns  the  process  ID  of  the  parent  of  the  current  process. 

SEE  ALSO 

gethostid(2) 
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GETPRI0RITY(2) 


SYSTEM  CALLS 


GETPRI0RITY(2) 


NAME 

getpriority,  setpriority  -  get/set  program  scheduling  priority 
SYNOPSIS 

#lncludQ  <8y0/re9ource«h> 

PRIO^PROCESS  0  /♦  proceaa  ♦/ 

#define  PRIO_PGRP  1  /*  process  group  */ 

#deflne  PRIO^USER  *  /*  user  Id  */ 

prio  s  getprlorlty(whichp  who) 

Int  prloy  whlchf  who| 

setpriority  (whichi  who^  P^^o) 
int  which,  who,  prio| 

DESCRIPTION 

The  scheduling  priority  of  the  process,  process  group,  or  user,  as  indicated  by  which  and  who  is 
obtained  with  the  getpriority  call  and  set  with  the  setpriority  call.  Which  is  one  of 
PRIOJPROCESS,  PRIO_PGRP,  or  PRIOJUSER,  and  who  is  interpreted  relative  to  which  (a  pro¬ 
cess  identifier  for  PRIO_PROCESS,  process  group  identifier  for  PRIO_PGRP,  and  a  user  ID  for 
PRIOJUSER).  Prio  is  a  value  in  the  range  -20  to  20.  The  default  priority  is  0;  lower  priorities 
cause  more  favorable  scheduling. 

The  getpriority  call  returns  the  highest  priority  (lowest  numerical  value)  enjoyed  by  any  of  the 
specified  processes.  The  setpriority  call  sets  the  priorities  of  all  of  the  specified  processes  to  the 
specified  value.  Only  the  super-user  may  lower  priorities, 

RETURN  value 

Since  getpriority  can  legitimately  return  the  value  -1,  it  is  necessary  to  clear  the  external  variable 
errno  prior  to  the  call,  then  check  it  afterward  to  determine  if  a  -1  is  an  error  or  a  legitimate 
value.  The  setpriority  call  returns  0  if  there  is  no  error,  or  -1  if  there  is. 

ERRORS 

Getpriority  and  setpriority  may  return  one  of  the  following  errors: 

[ESRCH]  No  proces8(es)  were  located  using  the  which  and  who  values  specified. 

[EINVAL]  Which  was  not  one  of  PRIOJPROCESS,  PRIOJ>GRP,  or  PRIO.USER. 

In  addition  to  the  errors  indicated  above,  setpriority  may  fail  with  one  of  the  following  errors 
returned: 

[EACCES]  A  process  was  located,  but  neither  its  effective  nor  real  user  ID  matched  the 
effective  user  ID  of  the  caller. 

[EACCES]  A  non  super-user  attempted  to  change  a  process  priority  to  a  negative  value. 

SEE  ALSO 

nice(l),  fork(2),  renice(8) 

BUGS 

It  is  not  possible  for  the  process  executing  setpriority  (  )  to  lower  any  other  process  down  to  its 
current  priority,  without  requiring  superuser  privileges. 
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GETRLIMIT(2) 


SYSTEM  CALLS 


GETBLIMIT(2) 


NAME 

getrlimit,  setrlimit  -  control  maximum  system  resource  consumption 
SYNOPSIS 

#lnc!ude  <By8/tlme.h> 

#include  <Bya/re80uree.h> 

getrllmlt(reflouree»  rip) 

Int  reBourcet 
Btruet  rttmlt  *rlp} 

BetrUmIt(r«aouree|  rip) 

Int  reBoure«| 
struct  rllmlt  ^rlpi 


DESCRIPTION 

Limits  on  the  consumption  of  system  resources  by  the  current  process  uid  each  process  it  creates 
may  be  obtained  with  the  getrlimit  call,  and  set  with  the  eetrlimit  call. 

The  retoiirce  parameter  is  one  of  the  following: 

RLIMIT_CPU  the  maximum  amount  of  cpu  time  (in  milliseconds)  to  be  used  by  each  pro 
cess. 


RLIMITJ'SIZE 

RLIMIT_DATA 

RLIMIT.STACK 


the  largest  size,  in  bytes,  of  any  single  file  which  may  be  created. 

the  maximum  size,  in  bytes,  of  the  data  segment  for  a  process;  this  defines 
how  far  a  program  may  extend  its  break  with  the  8brk(2)  system  call. 

the  maximum  size,  in  bytes,  of  the  stack  segment  for  a  process;  this  defines 
how  far  a  program’s  stack  segment  may  be  extended  automatically  by  the  sys¬ 
tem. 


the  largest  size,  in  bytes,  of  a  core  file  which  may  be  created. 

the  maximum  size,  in  bytes,  a  process’s  resident  set  size  may  grow  to.  This 
imposes  a  limit  on  the  amount  of  physical  memory  to  be  given  to  a  process;  if 
memory  is  tight,  the.  system  will  prefer  to  take  memory  from  processes  which 
are  exceeding  their  declared  resident  set  size. 

A  resource  limit  is  specified  as  a  soft  limit  and  a  bard  limit.  When  a  soft  limit  is  exceeded  a  pro¬ 
cess  may  receive  a  signal  (for  example,  if  the  cpu  time  is  exceeded),  but  it  will  be  allowed  to  con¬ 
tinue  execution  until  it  reaches  the  hard  limit  (or  modifies  its  resource  limit).  The  rlimit  structure 
is  used  to  specify  the  hard  and  soft  limits  on  a  resource, 

struct  rlimit  { 

int  rlim_cUr;  /*  Current  (soft)  limit  */ 

int  rlim_max;  /*  hard  limit  */ 

}:  \ 

Only  the  super-user  may  raise  the  maximum  limits.  Other  users  may  only  alter  rlim^eur  within 
the  range  from  0  to  rlim_maz  or  (irreversibly)  lowir  rlim_max. 

An  "infinite”  Value  for  a  limit  is  defined  as  RLIMIT_INFINITY  (Qx7ffWfff). 

Because  this  information  is  stored  in  the  per-process  information,  this  ^stem  call  must  be  exe¬ 
cuted  directly  by  the  shell  if  it  is  to  affect  all  future  processes  created  by  the  shell;  limit  b  thus  a 
built-in  command  to  csA(l). 

The  system  refuses  to  extend  the  data  or  stack  space  when  the  limits  would  be  exceeded  in  the 
normal  way:  a  break  call  fails  if  the  data  space  limit  is  reached,  or  the  process  is  killed  when  the 
stack  limit  is  reached  (since  the  stack  cannot  be  extended,  there  is  no  way  to  send  a  signal!). 


RLIMIT_CORE 
RLIMIT JRSS 
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GETRLIMIT(2) 


A  file  i/o  operation  which  would  create  a  file  which  is  too  large  will  cause  a  signal  SIGXFSZ  to  be 
generatedi  this  normally  terminates  the  process^  but  may  be  caught.  When  the  soft  cpu  time 
limit  is  exceeded,  a  signal  SIGXCPU  is  sent  to  the  offending  process. 

RETURN  VALUE 

A  0  return  value  indicates  that  the  call  succeeded,  changing  or  returning  the  resource  limit.  A 
return  value  of  -1  indicates  that  an  error  occurred,  and  an  error  code  is  stored  in  the  global  loca^ 
tion  cffne. 

ERRORS 

The  possible  errors  are: 

[EPAULT]  The  address  specified  for  rtp  is  invalid. 

[EPERN^  The  htmt  specified  to  ecirtimit  would  have 

raised  the  maximum:  limit  value,  and  the  caller  b  not  the  super-user. 

SEE  ALSO 

csb(l),  quota(2{ 

BUGS 

There  should  be  limit  and  unKrmt  commands  fn  sb^l)  as  well  aa  in  cah. 
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GETRUSAGE(2) 


NAME 

getrusage  -  get  information  about  resource  utilization 
SYNOPSIS 

#Inelude  <By8/time.h> 

#inelude  <sya/reaouree.h> 

#deflne  RUSAGE.SELF  0  /*  calUns  procesa  */ 

#defliie  RUSAGE.CHILDREN  -1  /*  terminated  ehUd  procewm  */ 

getrussge(who»  ruaage) 

Int  who| 

•tract  ruaage  *rucage} 


DESCRIPTION 

Getrmage  returns  information  about  the  resources  utilized  by  the  current  process,  or  all  its  ter¬ 
minated  child  processes.  The  who  parameter  is  one  of  RUSAGEJSELF  or 
RUSAGE_CHILDREN.  If  rusage  is  non-zero,  the  buffer  it  points  to  will  be  filled  in  with  the  fol- 


/*  user  time  used  •/ 


lowing  structure: 

struct  rusage  { 

struct  timeval  rujutime; 
struct  timeval  rujitime; 
int  ru_maxr88; 

int  rujxrss; 

int  rujdrss; 

int  ru^isrss; 

int  ru^infit; 

int  ru_in^fit; 

int  ru_p8wap; 

int  ru_inblock; 

int  rujoublock; 

int  ru_msgsBd; 

int  ru_msgrcv; 

int  ru_hsigna]s; 

int  ru_nvesw; 

int  rujnivcsw; 

}; 

The  fields  are  interpreted  as  follows: 


/*  system  time  used  V 

/*  integral  shared  memory  size  */ 
integral  unshared  data  size  */ 
/*  integral  unshared  stack  size  */ 
/*  page  reclaims  */ 
page  faults  ♦/ 

/♦swaps  •/ 

/♦  block  input  operations  */ 

/♦  block  output  operations  ♦/ 

/♦  messages  sent  ♦/ 

/♦  messages  received  ♦/ 

/♦  signals  received  ♦/ 

J*  voluntary  context  switches  ♦/ 
/♦  involuntary  context  switches  ♦/ 


rujutime 


the  total  amount  of  time  spent  executing  in  user  mode.  Time  is  given  in 
seconds:  microseconds. 


rujstime 

ru^maxrss 

rujxrss 


rujdrss 

rujsrss 


the  total  amount  of  time  spent  in  the  ^stem  executing  on  behalf  of  the 
proce88(es).  Time  is  given  in  &econds:inicroseconds. 

the  maximum  resident  set  size  utilized.  Size  is  given  in  pages  (1  page 
2Kbytes). 

an  ''integral”  value  indicating  the  amount  of  memory  used  which  was  also 
shared  among  other  processes.  This  value  is  expressed  in  units  of  pages  ♦  clock 
ticks  (1  tick  =  1/50  second).  The  value  is  calculated  by  summing  the  number  of 
shared  memory  pages  in  use  each  time  the  internal  system  clock  ticks,  and  then 
averaging  over  1  second  intervals. 

an  integral  value  of  the  amount  of  unshared  memory  residing  in  the  data  seg¬ 
ment  of  a  process.  The  value  is  given  in  pages  ♦  clock  ticks. 

an  integral  value  of  the  amount  of  unshared  memory  residing  in  the  stack  seg¬ 
ment  of  a  process.  The  value  is  given  in  pages  *  clock  ticks. 
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ru_mmflt 

ru_niajfit 

ru.nswap 

rujnblock 

ru.outblock 

ru^insgsnd 

ru^msgrcv 

ru^nsignals 

rujttvcsw 

rujiivcsw 


the  number  of  page  faults  serviced  without  any  i/o  activity;  here  i/o  activity  is 
avoided  by  ‘^reclaiming”  a  page  frame  from  the  list  of  pages  awaiting  realloca¬ 
tion. 

the  number  of  page  faults  serviced  which  required  i/o  activity. 

the  number  of  times  a  process  was  “swapped”  out  of  main  memory. 

the  number  of  times  the  file  system  had  to  perform  input. 

the  number  of  times  the  file  system  had  to  perform  output. 

the  number  of  ipc  messages  sent. 

the  number  of  ipc  messages  received. 

the  number  of  signals  delivered. 

the  number  of  times  a  context  switch  resulted  due  to  a  process  voluntarily  giving 
up  the  processor  before  its  time  slice  was  completed  (usually  to  await  availability 
of  a  resource). 

the  number  of  times  a  context  switch  resulted  due  to  a  higher  priority  process 
becoming  runnable  or  because  the  current  process  exceeded  its  time  slice. 


NOTES 

The  numbers  ru_inblock  and  ru^outbiock  account  only  for  real  i/o;  data  supplied  by  the  cacheing 
mechanism  is  charged  only  to  the  first  process  to  read  or  write  the  data. 

SEE  ALSO 

gettimeofday(2),  wait(2) 

BUGS 

There  is  no  way  to  obtain  information  about  a  child  process  which  has  not  yet  terminated. 
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SYSTEM  CALLS 


GETS0CKNAME(2) 


NAME 

getsockname  -  get  socket  name 
SYNOPSIS 

get8ockname(s,  name,  namelen) 

Int  a; 

struct  sockaddr  ^am^ 

Int  *namelen| 

DESCRIPTION 

GtiBocknamt  returns  the  current  name  for  the  specified  socket.  The  name/en  parameter  should  be 
ijiitialized  to  indicate  the  amount  of  space  pointed  to  by  name.  On  retain  it  contains  the  actual 
size  of  the  name  returned  (in  bytes). 

DIAGNOSTICS 

A  0  is  returned  if  the  call  succeeds,  -1  if  it  faib. 


ERRORS 

The  call  succeeds  unless: 


(EBADFI 

jENOTSOCK) 

lENOBUFS) 

lEFAULTl 


The  argument  s  is  not  a  valid  descriptor. 

The  argument  s  is  a  file,  not  a  socket. 

Insufficient  resources  were  available  in  the  ^stem  to  perform  the  operation. 

The  name  parameter  points  to  memory  not  in  a  valid  part  of  the  process  address 
space. 


SEE  ALSO 

bind(2),  socket(2),  getpeername(2) 

BUGS 

Names  bound  to  sockets  in  the  UNIX  domain  are  inaccessible;  QetBoekname  returns  a  zero  length 
name. 
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NAME 

getsockopt,  setsockopt  -  get  and  set  options  on  sockets 
SYNOPSIS 

#lnciude  <sy6/type8«h> 

#include  <0y8/0ocket*h> 

geteoekopt(8|  level,  optnamci  optvalt  option) 
int  9,  level,  optnamei 
char  *optvalj 
int  "^optlen^ 

8et80ckopt(89  level,  optname,  optval,  optlen) 

Int  6,  leveli  optnamei 
char  ’^optvali 
int  optical 

DESCRIPTION 

Getsockopt  and  setsockopt  manipulate  options  associated  with  a  socket.  Options  may  exist  at 
multiple  protocol  levels;  they  are  always  present  at  the  uppermost  “socket**  level* 

When  manipulating  socket  options  the  level  at  which  the  option  resides  and  the  name  of  the 
option  must  be  specified.  To  manipulate  options  at  the  “socket**  level,  level  is  specified  as 
SOL_SOCKET.  To  manipulate  options  at  any  other  level  the  protocol  number  of  the  appropriate 
protocol  controlling  the  option  is  supplied.  For  example,  to  indicate  an  option  is  to  be  inter¬ 
preted  by  the  TCP  protocol,  level  should  be  set  to  the  protocol  number  of  TCP;  see 
g€tprotoent{3Ny 

The  parameters  optval  and  optlen  are  used  to  access  option  values  for  setsockopt.  For  getsockopt 
they  identify  a  buffer  in  which  the  value  for  the  requested  option(s)  are  to  be  returned*  For  get- 
sockoptf  optlen  is  a  value-result  parameter,  initially  containing  the  size  of  the  buffer  pointed  to  by 
optval,  and  modified  on  return  to  indicate  the  actual  size  of  the  value  returned.  If  no  option 
value  is  to  be  supplied  or  returned,  optval  may  be  supplied  as  0. 

Optname  and  any  specified  options  are  passed  uninterpreted  to  the  appropriate  protocol  module 
for  interpretation.  The  include  file  Ksysf 80cket,h>  contains  definitions  for  “socket**  level 
options;  see  soeket{2).  Options  at  other  protocol  levels  vary  in  format  and  name,  consult  the 
appropriate  entries  in  (4P). 

RETURN  VALUE 

A  0  is  returned  if  the  call  succeeds,  -1  if  it  fails* 

ERRORS 

The  call  succeeds  unless: 

[EBADF]  The  argument  s  is  not  a  valid  descriptor. 

[ENOTSOCKj  The  argument  ^  is  a  file,  not  a  socket. 

(ENOPROTOOPT]  The  option  is  unknown* 

[EFAULT]  The  options  are  not  in  a  valid  part  of  the  process  address  space. 

SEE  ALSO 

80cket(2),  getprotoent(3bl) 
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NAME 

gettimeofday,  settimeofday  -  get/set  date  and  time 
SYNOPSIS 

#include  <8ys/t!me.h> 

gettlmeofday(tpi  tsp) 
struct  timevat  Hp| 
struct  tlmesone  ’^tspi 

settIineofday(tpi  tsp) 
struct  tlmevsi  Hp| 
struct  tlmesone  ^tspi 

DESCRIPTION 

Gtiiitneofday  returns  the  system’s  notion  of  the  current  Greenwich  time  and  the  current  time 
zone.  Time  returned  is  expressed  in  seconds  and  microseconds  since  midnight  January  1,  1970. 

The  structures  pointed  to  by  tp  and  izp  are  defined  in  <sys/rtme.A>  as: 

struct  timeval  { 

ujong  tv^sec;  /*  seconds  since  Jan.  1,  1970  *j 

long  tv  usee;  /*  and  microseconds 

}; 

struct  timezone  { 

int  tz  jninuteswest;  /*  of  Greenwich  *•'/ 

int  tz^dsttime;  /♦  type  of  dst  correction  to  apply  */ 

}; 

The  iimtzont  structure  indicates  the  local  time  zone  (measured  in  minutes  of  time  westward  from 
Greenwich),  and  a  flag  that,  if  nonzero,  indicates  that  Daylight  Saving  time  applies  locally  during 
the  appropriate  part  of  the  year. 

If  fp  and/or  tzp  is  a  zero  pointer,  the  corresponding  information  will  not  be  returned  or  set. 

Only  the  super-user  may  set  the  time  of  day. 

RETURN 

A  0  return  value  indicates  that  the  call  succeeded.  A  -1  return  value  indicates  an  error  occurred, 
and  in  this  case  an  error  code  is  stored  into  the  global  variable  errno. 

ERRORS 

The  following  error  codes  may  be  set  in  errno: 

[EFAULTj  An  argument  address  referenced  invalid  memory. 

[EPERM]  A  user  other  than  the  super-user  attempted  to  set  the  time. 

SEE  ALSO 

date(l),  ctime(3) 

BUGS 

Time  is  never  correct  enough  to  believe  the  microsecond  values.  There  should  a  mechanism  by 
which,  at  least,  local  clusters  of  systems  might  synchronize  their  clocks  to  millisecond  granularity. 
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O 


NAME 

getuid^  geteuid  -  get  user  identity 

SYNOPSIS 

uld  S3  getuid() 
ini  uld| 

cuid  S3  geteuld() 

Int  eu!d| 

DESCRIPTION 

^eiuid  returns  the  real  user  ID  of  the  current  process,  geteuid  the  effective  user  ID. 

T}ie  real  user  ID  identifies  the  person  who  is  logged  In.  The  effective  user  ID  gives  the  process 
additional  permissions  during  execution  of  **set»U8er*ID”  mode  processes,  which  use  getuid  to 
determine  the  reahuser-id  of  the  process  which  invoked  them, 

SEE  ALSO 

getgid(2),  8etreuid(2) 
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I0CTL(2) 


NAME 

ioctl  -  control  device 
SYNOPSIS 

^Include  <nys/loetI.h> 

loetl(d,  request,  argp) 

Int  d,  request) 
char  ^argp) 

DESCRIPTION 

loetl  perforins  a  variety  of  functions  on  open  descriptors.  In  particular,  many  operating  cbarac* 
teristics  of  character  special  files  (e.g.  terminab)  may  be  controlled  with  ioctl  requests.  The  write¬ 
ups  of  various  devices  in  section  4  dbcuss  how  ioctl  applies  to  them. 

An  ioctl  requcft  has  encoded  in  it  whether  the  argument  b  an  “in”  parameter  or  “out”  parame¬ 
ter,  and  the  size  of  the  argument  argp  in  bytes.  Macros  and  defines  used  in  specifying  an  ioctl 
requeot  are  located  in  the  file  <$yffioetl.h>. 

RETURN  VALUE 

If  an  error  has  occurred,  a  value  of  -1  b  returned  and  errno  b  set  to  indicate  the  error. 

If  no  error  has  occurred  (using  a  STANDARD  device  driver),  a  value  of  0  b  returned. 

ERRORS 

Ioctl  will  fail  if  one  or  more  of  the  following  are  true; 

(EBADF)  D  is  not  a  valid  descriptor. 

(ENOTTY)  D  is  not  associated  with  a  character  special  device. 

(ENOTTYj  The  specified  request  does  not  apply  to  the  kind  of  object  which  the  descriptor  d 

references. 

[EINVAL]  Requestor  ar^p  is  not  valid. 

SEE  ALSO 

execve(2),  fcntl(2),  mtio(4),  tty(4) 
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NAME 

kill  -  send  signal  to  a  process 

SYNOPSIS 

kill(ptd,  Big) 

Ini  pidt  Big; 

DESCRIPTION 

Kill  sends  the  signal  eig  to  a  process^  specified  by  the  process  number  pid,  Sig  may  be  one  of  the 
signals  specified  in  9igvtc{2)f  or  it  may  be  0^  in  which  case  error  checking  is  performed  but  no  sig¬ 
nal  is  actually  sent  This  can  be  used  to  check  the  validity  of  pid. 

The  sending  and  receiving  processes  must  have  the  same  effective  user  ID,  otherwise  this  call  is 
restricted  to  the  super-user.  A  single  exception  is  the  signal  SIGCONT  which  may  always  be  sent 
to  any  child  or  grandchild  of  the  current  process. 

If  the  process  number  is  0,  the  signal  is  sent  to  all  other  processes  in  the  sender’s  process  group; 
this  is  a  variant  of  killpg{2). 

If  the  process  number  is  -1^  and  the  user  is  the  super-user,  the  signal  is  broadcast  universally 
except  to  system  processes  and  the  process  sending  the  signal. 

Processes  may  send  signals  to  themselves. 

RETURN  VALUET 

Upon  successful  completion,  a  value  of  0  is  returned.  Otherwise,  a  value  of  -1  is  returned  and 
errno  is  set  to  indicate  the  error. 

ERRORS 

Kill  will  fail  and  no  signal  will  be  sent  if  any  of  the  following  occur: 

[EINVAL]  Sig  is  not  a  valid  signal  number. 

[ESRCH]  No  process  can  be  found  corresponding  to  that  specified  by  pid. 

[EPERM]  The  sending  process  is  not  the  super-user  and  its  effective  user  id  does  not  match 

the  effective  user-id  of  the  receiving  process. 

SEE  ALSO 

getpid(2),  getpgrp(2).  killpg(2),  sigvec(2) 
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NAME 

killpg  -  send  signal  to  a  process  group 

SYNOPSIS 

kUIpsCpgrp,  sig) 
tnt  pgrpi  ilg; 

DESCRIPTION 

Killpg  sends  the  signal  sig  to  the  process  group  pgrp.  See  9igvec(2)  for  a  list  of  signals. 

The  sending  process  and  members  of  the  process  group  must  have  the  same  effective  user  ID,  oth- 
epvise  this  call  is  restricted  to  the  super-user.  As  a  single  special  case  the  continue  signal 
3jGCONT  may  be  sent  to  any  process  which  is  a  descendant  of  the  current  process. 

RETURftJ  VALUE 

Upon  successful  completion,  a  value  of  0  is  returned.  Otherwise,  a  value  of  -1  is  returned  and  the 
global  variable  errno  is  set  to  indicate  the  error. 

ERRORS 

Killpg  will  fail  and  no  signal  will  be  sent  if  any  of  the  following  occur: 

(EINVALj  Sig  is  not  a  valid  signal  number. 

[ESRCHJ  No  process  were  found  in  the  specified  process  group. 

[EPERMj  The  sending  process  is  not  the  super-user  and  one  or  more  of  the  target  processes 

has  an  effective  user  ID  different  from  that  of  the  sending  process. 

SEE  ALSO 

k})l(2),  getpgrp(2),  8igvec(2) 
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L1NK(2) 


NAME 

link  -  make  a  hard  link  to  a  file 

SYNOPSIS 

iliik(namel,  name2) 
char  *namel,  *name2t 

DESCRIPTION 

A  hard  link  to  namtl  is  created;  the  link  has  the  name  nameS.  Namel  must  exist. 

With  hard  links,  both  namel  and  nameS  must  be  in  the  same  file  system.  Unless  the  caller  is  the 
super'user,  namel  must  not  be  a  directory.  Both  the  old  and  the  new  link  share  equal  access  and 
ri^ts  to  the  underlying  object. 

RETURN  VALUE 

Upon  successful  completion,  a  value  of  0  is  returned.  Otherwise,  a  value  of  -1  is  returned  and 
errno  is  set  to  indicate  the  error. 

ERRORS 

Link  wOl  fail  and  no  link  will  be  created  if  one  or  more  of  the  following  arc  true: 

(EPERMJ 
(ENOENTl 
(ENOTDml 
(ENOENT) 

(EACCESj 
(ENOENT) 

(EEXIST) 

[EPERN^ 

lEXDEV) 

(EACCES) 

[EROFS] 

(EFAULT) 

(ELOOP) 

SEE  ALSO 

symlink(2),  unlink(2) 


Either  pathname  contains  a  byte  with  the  high-order  bit  set. 

Either  pathname  was  too  long. 

A  component  of  either  path  prefix  is  not  a  directory. 

A  component  of  either  path  prefix  does  not  exist. 

A  component  of  either  path  prefix  denies  search  permission. 

The  file  named  by  namel  does  not  exist. 

The  link  named  by  nameS  does  exist. 

The  file  named  by  namel  is  a  directory  and  the  effective  user  ID  is  not  super- 
user. 

The  link  named  by  nameS  and  the  file  named  by  namel  are  on  different  file  sys¬ 
tems. 

The  requested  link  requires  writing  in  a  directory  with  a  mode  that  denies  write 
permission. 

The  requested  link  requires  writing  in  a  directory  on  a  read-only  file  system. 

One  of  the  pathnames  specified  is  outside  the  process’s  allocated  address  space. 
Too  many  symbolic  links  were  encountered  in  translating  the  pathname. 
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NAME 

listen  -  listen  for  connections  on  a  socket 

SYNOPSIS 

llBteii(a»  backlog) 
tnt  St  backlog; 

DESCRIPTION 

To  accept  connections^  a  socket  is  first  created  with  90ckti(2)t  a  backlog  for  incoming  connections 
is  specified  with  /i>lcn(2)  and  then  the  connections  are  accepted  with  sccep;(2)*  The  lieten  call 
applies  only  to  sockets  of  type  SOCK.STREAM  or  SOCKJPKTSTREAM. 

The  backlog  parameter  defines  the  maximum  length  the  queue  of  pending  connections  may  grow 
to.  If  a  connection  request  arrives  with  the  queue  full  the  client  will  receive  an  error  with  an  indn 
cation  of  ECONNREFUSED. 

RETURN  VALUE 

A  0  return  value  indicates  success;  -1  indicates  an  error. 

ERRORS 

The  call  fails  if: 

(EBADF|  The  argument  s  is  not  a  valid  descriptor. 

[ENOTSOCK]  The  argument  s  is  not  a  socket. 

(EOPNOTSUPP)  The  socket  is  not  of  a  type  that  supports  the  operation  lieten, 

SEE  ALSO 

accept(2),  connect(2),  socket(2) 

BUGS 

The  backlog  is  currently  limited  (silently)  to  5. 
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SYSTEM  CALLS 


LSEEK(2) 


NAME 

Iseek,  tell  -  move  read/write  pointer 
SYNOPSIS 

#deflne  L_SET  0  f*  set  the  seek  pointer  */ 

#deflne  L_INCR  1  /*  Increment  the  seek  pointer  */ 

#deflne  L_XTND  2  f*  extend  the  file  sice  */ 

pos  ass  lseck(d,  oflkett  whence) 

Int  pos{ 

Int  d,  offset,  wheneet 
DESCRIPTION 

The  deBciiptor  d  refers  to  a  file  or  device  open  for  reading  and/or  writing.  Litek  sets  the  file 
pointer  of  d  as  follows: 

If  whence  is  L_SET,  the  pointer  to  set  to  offset  bytes. 

If  whence  is  L_INCR,  the  pointer  to  set  to  its  current  location  plus  offset. 

If  whence  is  LJCTND,  the  pointer  is  set  to  the  size  of  the  file  plus  offset. 

Upon  successful  completion,  the  resulting  pointer  location  as  measured  in  bytes  from  beginning  of 
the  file  is  returned.  Some  devices  are  incapable  of  seeking.  The  value  of  the  pointer  associated 
with  such  a  device  to  undefined. 

The  obsolete  function  tetl(fiides)  is  identical  to  tseekfJUdes,  OL,  L_INCR). 

NOTES  : 

Seeking  far  beyond  the  end  of  a  file,  then  writing,  creates  a  gap  or  “hole”,  which  occupies  no  phy> 
sical  space  and  reads  as  zeros. 

RETURN  VALUE 

Upon  successful  completion,  a  non-negative  integer,  the  current  file  pointer  value,  to  returned. 
Otherwise,  a  value  of  -1  to  returned  and  errno  to  set  to  indicate  the  error. 

ERRORS 

Lseek  will  fail  and  the  file  pointer  will  remun  unchanged  if: 

(EBADF]  Fildes  is  not  an  open  file  descriptor. 

(ESPIPE)  Fildes  to  associated  with  a  pipe  or  a  socket. 

{EINVAL]  Whence  to  not  a  proper  value. 

[EINVAL]  The  resulting  file  pointer  would  be  negative. 

SEE  ALSO 

dup(2),  open(2) 
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MKDIR(2) 


SYSTEM  CALLS 


MKDIR(2) 


NAME 

mkdir  -  make  a  directoiy  file 

SYNOPSIS 

mkdlr(p«tht  mode) 
char  *path) 

Int  model 

DESCRIPTION 

Mkdir  creates  a  new  directoiy  file  with  name  path.  The  mode  of  the  new  file  u  initialized  from 
mode.  (The  protection  part  of  the  mode  is  modified  by  the  process’s  mode  mask;  see  umMk(2)). 

The  directory’s  owner  ID  is  set  to  the  process’s  effective  user  ID.  The  directory’s  group  ID  is  set 
to  that  of  the  parent  directory  in  which  it  is  created. 

The  low-order  9  bits  of  mode  are  modified  by  the  process’s  file  mode  creation  mask:  all  bits  set  in 
the  process’s  file  mode  creation  mask  are  cleared.  See  ums»ii;(2). 

RETURN  VALUE 

A  0  return  value  indicates  success.  A  -1  return  value  indicates  an  error,  and  an  error  code  is 
stored  in  srrno. 


ERRORS 

Mkdir  will  fail  and  no  directory  will  be  created  if: 


(EPERM] 

(EPERl^ 

(ENOTDIRl 

lENOENTj 

{EROFS] 

(EEXIST) 

[EFAULT] 

(ELOOPI 

[£10| 

SEE  ALSO 


The  process’s  effective  user  ID  is  not  super^user. 

The  palk  argument  contains  a  byte  with  the  high-order  bit  set. 

A  component  of  the  path  prefix  is  not  a  directoiy. 

A  component  of  the  path  prefix  does  not  exist. 

The  named  file  resides  on  a  read-only  file  system. 

The  named  file  exists. 

Path  points  outside  the  process’s  allocated  address  space. 

Too  many  symbolic  links  were  encountered  in  translating  the  pathname. 
An  I/O  error  occured  while  writing  to  the  file  system. 


chmod(2),  stat(2),  umask(2) 
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MKNOD(2) 


SYSTEM  CALLS 


MKNOD(2) 


NAME 

mkDod  -  make  a  special  file 
SYNOPSIS 

mknod(path,  mode»  dev) 
char  "^path; 

Int  modof  dev) 

DESCRIPTION 

MknQd  creates  a  new  file  whose  name  is  path.  The  mode  of  the  new  file  (including  special  file  bits) 
is  initialized  from  mode.  (The  protection  part  of  the  mode  is  modified  by  the  process’s  mode 
mask;  see  uma9i!;(2)).  The  first  block  pointer  of  the  Lnode  is  initialized  from  dev  and  is  used  to 
specify  which  device  the  special  file  refers  to. 

If  mode  indicates  a  block  or  character  special  file,  dev  is  a  configuration  dependent  specification  of 
a  character  or  block  I/O  device.  If  mode  does  not  indicate  a  block  special  or  character  special 
device,  dev  is  ignored. 

Mknod  may  be  invoked  only  by  the  super-user. 

RETURN  VALUE 

Upon  successful  completion  a  value  of  0  is  returned.  Otherwise,  a  value  of  -1  is  returned  and 
errno  is  set  to  indicate  the  error. 


ERRORS 

Mknod  will  fail  and  the  file  mode  will  be  unchanged  if: 

(EPERM)  The  process’s  effective  user  ID  is  not  super^user. 

{fePERM]  The  pathname  contains  a  character  with  the  high-order  bit  set. 

[EN0TD1R|  A  component  of  the  path  prefix  is  not  a  directory. 

[ENOENTj  A  component  of  the  path  prefix  does  not  exist. 

(EROFS]  The  named  file  resides  on  a  read-only  file  system. 

[EEXIST]  The  named  file  exists. 

[EFAULT]  Path  points  outside  the  process's  allocated  address  space. 

[ELOOP]  Too  many  symbolic  links  were  encountered  in  translating  the  pathname. 

SEE  ALSO 

chmod(2),  stat(2),  umask(2) 
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MMAP(2) 


SYSTEM  CALLS 


MMAP(2) 


NAME 

mmap  -  map  pages  of  memory 
SYNOPSIS 

#inelude  <8y0/mman.h> 

#inelude  <8y8/type8«h> 

mmap(addr,  leni  prot,  aharei  fd,  ofl) 
caddr^t  addri  int  len»  prot,  share,  fd{  olTjfe  ofTf 

DESCRIPTION 

N«B«t  This  call  Is  not  completely  Implemented  In 

Mmap  maps  the  pages  starting  at  addr  and  continuing  for  itn  bytes  from  the  object  represented 
by  the  descriptor  /d,  at  the  current  file  position  of  offset  off.  The  parameter  share  specifies 
whether  modifications  made  to  this  mapped  copy  of  the  page  are  to  be  kept  private  or  are  to  be 
shared  with  other  references.  The  parameter  proi  specifies  the  accessibility  of  the  mapped  pages. 
The  addr  and  ten  parameters  and  the  sum  of  the  current  position  in  fd  and  the  parameters 
must  be  multiples  of  the  page  size  (found  using  the  geipage8ize(2)  call). 

Pages  are  automatically  unmapped  at  close. 

RETURN  VALUE 

The  call  returns  0  on  success,  -1  on  failure. 


ERRORS 

The  mmap  call  will  fail  if: 


[EINVALj  The  argument  address  or  length  is  not  a  multiple  of  the  page  size  as  returned  by 
getpaQesize{2),Qr  the  length  is  negative. 

[EINVAL]  The  entire  range  of  pages  specified  in  the  call  is  not  part  of  data  space. 

(EINVALj  The  specified  fd  does  not  refer  to  a  character  special  device  which  supports  mapping 
(e.g.  a  frame  buffer). 

[EINVALj  The  specified  fd  is  not  open  for  reading  and  read  access  is  requested,  or  not  open  for 
writing  when  write  access  is  requested. 


[EINVALj  The  sharing  mode  was  not  specified  as  MAP_SHARED. 
SEE  ALSO 

getpage8ize(2),  munmap(2),  close(2) 
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MOUNT(2) 


SYSTEM  CALLS 


M0UNT(2) 


NAME 

mount,  umount  —  mount  or  remove  file  ^stem 
SYNOPSIS 

inount(speciAlf  namep  rwflag) 
char  *flpeclal»  *name| 
int  rwfiagi 

umount(flpee!a!) 
char  *speclal| 

DESCRIPTION 

Mount  announces  to  the  system  that  a  removable  file  system  has  been  mounted  on  the  block* 
structured  special  file  opecial;  from  now  on,  references  to  file  name  will  refer  to  the  root  file  on  the 
newly  mounted  file  system.  Special  and  name  are  pointers  to  null- terminated  strings  containing 
the  appropriate  path  names. 

Name  must  exist  already.  Name  must  be  a  directory.  Its  old  contents  are  inaccessible  while  the 
file  system  is  mounted. 

The  rwflag  argument  determines  whether  the  file  ^stem  can  be  written  on;  if  it  is  0  writing  is 
allowed,  if  non*zero  no  writing  is  done.  Physically  write-protected  and  magnetic  tape  file  systems 
must  be  mounted  read-only  or  errors  will  occur  when  access  times  are  updated,  whether  or  not 
\  any  explicit  write  is  attempted. 

Umount  announces  to  the  system  that  the  epecial  file  is  no  longer  to  contain  a  removable  file  sys¬ 
tem.  The  associated  file  reverts  to  its  ordinary  interpretation. 

RETURN  VALUE 

Mount  returns  0  if  the  action  occurred,  -1  if  epeeial  is  inaccessible  or  not  an  appropriate  file;  if 
name  does  not  exist;  if  special  is  already  mounted;  if  name  is  in  use;  or  if  there  are  already  too 
many  file  systems  mounted. 

Umount  returns  0  if  the  action  occurred;  -1  if  if  the  special  file  is  inaccessible  or  does  not  have  a 
mounted  file  i^stem,  or  if  there  are  active  files  in  the  mounted  file  system. 

ERRORS 

h^unt  will  fail  when  one  of  the  following  occurs: 

[NODEV]  The  caller  is  not  the  super-user. 

[NODEV]  Special  does  not  exist. 

[ENOTBLK]  Special  is  not  a  block  device. 

|ENXIO|  The  major  device  number  of  special  is  out  of  range  (this  indicates  no  device 

driver  exists  for  the  associated  hardware). 

[EPERM]  The  pathname  contains  a  character  with  the  high-order  bit  set. 

(ENOTDIR)  A  component  of  the  path  prefix  in  name  is  not  a  directory. 

(EROFSj  Name  resides  on  a  read-only  file  system. 

(ElBUSY)  Name  is  not  a  directory,  or  another  process  currently  holds  a  reference  to  it. 

(EBUSYj  No  space  remains  in  the  mount  table. 

(EBUSY]  The  super  block  for  the  file  system  had  a  bad  magic  number  or  an  out  of  range 

block  size. 

(EBUSY]  Not  enough  memory  was  available  to  read  the  cylinder  group  information  for  the 

file  system. 

[EBUSY]  An  i/o  error  occurred  while  reading  the  super  block  or  cylinder  group  informap 

tion. 
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M0UNT(2) 


SYSTEM  CALLS 


MOUNT(2) 


Vmount  may  fail  with  one  of  the  following  errors: 

[NODEV]  The  caller  is  not  the  super-user. 

[NODEV]  Special  does  not  exist. 

(ENOTBLKj  Special  is  not  a  block  device. 

[ENXIO]  The  major  device  number  of  epeciat  is  out  of  range  (this  indicates  no  device 

driver  exists  for  the  associated  hardware). 

[EINVAL]  The  requested  device  is  not  in  the  mount  table. 

[EBUSY]  A  process  is  holding  a  reference  to  a  file  located  on  the  file  system. 

SEE  ALSO 

mount(8),  umount(8) 

BUGS 

The  error  codes  are  in  a  state  of  disarray;  too  many  errors  appear  to  the  caller  as  one  value. 


60 


Last  change;  29  August  1983 


Sun  Release  1.1 


MUNMAP(2) 


SYSTEM  CALLS 


MUNMAP(2) 


NAME 

munmap  -  unmap  pages  of  memory 
SYNOPSIS 

#iiielud6  <mman.h> 

munmap(addr|  len) 
eaddr^t  add?;  int  len; 


DESCRIPTION 

N«B*s  This  call  Is  not  completely  Implemented  In  4»2« 

Munmap  causes  the  pages  starting  at  addr  and  continuing  for  len  bytes  to  refer  to  private  pages 
which  will  be  initialized  to  zero  on  reference. 


RETURN  VALUE 

The  call  returns  -1  on  error,  0  on  success. 

ERRORS 

The  call  fails  if  any  of  the  following: 

[EINVAL]  The  argument  address  or  length  is  not  a  multiple  of  the  page  size  as  returned  by 
getpage8ize{2)f0r  the  length  is  negative. 

[EINVAL]  The  entire  range  of  pages  specified  in  the  call  is  not  part  of  data  space. 

SEE  ALSO 

brk  (2),  mmap(2),  close(2) 
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0PEN(2) 


SYSTEM  CALLS 


0PEN(2) 


NAME 

open  -  open  a  file  for  reading  or  writing,  or  create  a  new  file 
SYNOPSIS 

#include  <sy8/file*h> 

open(p&th|  flagtf  mode) 
char  *path) 
iat  flaga,  mode; 


DESCRIPTION 

Optn  opens  the  file  path  for  reading  and/or  writing,  as  specified  by  the  flag9  argument  and  returns 
a  descriptor  for  that  file.  The  ftaga  argument  indicate  the  file  is  to  be  created  if  it  does  not 
already  exist  (by  specifying  the  0_CREAT  flag),  in  which  case  the  file  is  created  with  mode  mode 
as  described  in  chmod{2)  and  modified  by  the  process*  umask  value  (see  nmaak(2))« 

Path  is  the  address  of  a  string  of  ASCII  characters  representing  a  path  name,  terminated  by  a  null 
character.  The  flags  specified  are  formed  by  er’ing  the  following  values 


OJIDONLY 

O.WRONLY 

0_RDWR 

O.NDELAY 

O^PEND 

O^CREAT 

O^TRUNC 

O^EXCL 


open  for  reading  only 
open  for  writing  only 
open  for  reading  and  writing 
do  not  block  on  open 
append  on  each  write 
create  file  if  it  does  not  exist 
truncate  size  to  0 
error  if  create  and  file  exists 


Opening  a  file  with  0_APPEND  set  causes  each  write  on  the  file  to  be  appended  to  the  end.  If 
O JFRUNC  is  specified  and  the  file  exists,  the  file  is  truncated  to  zero  length.  If  OJBXCL  is  set 
with  0_CREAT,  then  if  the  file  already  exists,  the  open  returns  an  error.  This  can  be  used  to 
implement  a  simple  exclusive  access  locking  mechanism.  If  the  0_NDELAY  flag  is  specified  and 
the  open  call  would  result  in  the  process  being  blocked  for  some  reason  (e.g.  waiting  for  carrier  on 
a  dialup  line),  the  open  returns  immediately.  The  first  time  the  process  attempts  to  perform  i/o 
on  the  open  file  it  will  block  (not  currently  implemented). 

Upon  successful  completion  a  non*'negative  integer  termed  a  file  descriptor  is  returned.  The  file 
pointer  used  to  mark  the  current  position  within  the  file  is  set  to  the  beginning  of  the  file. 

The  new  descriptor  is  set  to  remain  open  across  txceve  system  calls;  sec  cfose(2). 

There  is  a  system  enforced  limit  on  the  number  of  open  file  descriptors  per  process,  whose  value  is 
returned  by  the  getdtabteeize{2)  call. 


RETURN  VALUE 

The  value  -1  is  returned  if  an  error  occurs,  and  external  variable  errno  is  set  to  indicate  the  cause 
of  the  error.  Otherwise  a  non-negative  numbered  file  descriptor  for  the  new  open  file  is  returned. 


ERRORS 

Open  fails  if: 

(EPERM] 

jENOTDIR] 

[ENOENT] 

[EACCESj 

[EACCESj 

[EISDIRj 


The  pathname  contains  a  character  with  the  high-order  bit  set. 

A  component  of  the  path  prefix  is  not  a  directory. 

O^CREAT  is  not  set  and  the  named  file  does  not  exist. 

A  component  of  the  path  prefix  denies  search  permission. 

The  required  permissions  (for  reading  and/or  writing)  are  denied  for  the  named 
file. 

The  named  file  is  a  directory,  and  the  arguments  specify  it  is  to  be  opened  for 
writing. 
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(EROFS)  The  named  file  resides  on  a  read-only  file  system,  and  the  file  is  to  be  modified. 

(EMFILEl  {OPEN_MAX}  file  descriptors  are  currently  open, 

[ETXTBSY)  The  file  is  a  pure  procedure  (shared  text)  file  that  is  being  executed  and  the  open 
call  requests  write  access. 

|EFAULT)  Path  points  outside  the  process’s  allocated  address  space. 

[ELOOPj  Too  many  symbolic  links  were  encountered  in  translating  the  pathname. 

(EEXISTj  0_EXCL  was  specified  and  the  file  exists. 

{ENXIOj  The  0_NDELAY  flag  is  given,  and  the  file  is  a  communications  device  on  which 

there  is  no  carrier  present. 

[EOPNOTSUPP) 

An  attempt  was  made  to  open  a  socket  (not  currently  implemented). 


SEE  ALSO 

chmod(2),  clo8e(2),  dup(2),  lseek(2),  read(2),  write(2),  umask(2) 


o 


o 
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PIPE(2) 


SYSTEM  CALLS 


PIPE(2) 


NAME 

pipe  -  create  an  interprocess  communication  channel 

SYNOPSIS 

plpe(flldes) 

Int  flldea[2]| 

DESCRIPTION 

The  pipt  system  call  creates  an  I/O  mechanism  called  a  pipe.  The  file  descriptors  returned  can  be 
used  in  read  and  write  operations.  When  the  pipe  is  written  using  the  descriptor  fildt8\l\  up  to 
4096  bytes  of  data  are  buffered  before  the  writing  process  is  suspended.  A  read  using  the  descrip¬ 
tor  will  pick  up  the  data. 

It  is  assumed  that  after  the  pipe  has  been  set  up,  two  (or  more)  cooperating  processes  (created  by 
subsequent  fork  calls)  will  pass  data  through  the  pipe  with  read  and  write  cdls. 

The  shell  has  a  syntax  to  set  up  a  linear  array  of  processes  connected  by  pipes. 

Read  calls  on  an  empty  pipe  (no  buffered  data)  with  only  one  end  (all  write  file  descriptors  closed) 
returns  an  end-of-file. 

Pipes  are  really  a  special  case  of  the  so€ketpair{2)  call  and,  in  fact,  are  implemented  as  such  in 
the  ^8 tern. 

A  signal  is  generated  if  a  write  on  a  pipe  with  only  one  end  is  attempted. 

RETURN  VALUE 

The  function  value  zero  is  returned  if  the  pipe  was  created;  -1  if  an  error  occurred. 

ERRORS 

The  pipe  call  will  fail  if: 

[EMFILE]  Too  many  descriptors  are  active. 

[EFAULT]  The  fUdes  buffer  is  in  an  invalid  area  of  the  process’s  address  space. 

SEE  ALSO 

8h(l),  read(2),  write(2),  fork(2),  socketpair(2) 

BUGS 

Should  more  than  4096  bytes  be  necessary  in  any  pipe  among  a  loop  of  processes,  deadlock  will 
occur. 
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NAME 

profit  ~  execution  time  profile 
SYNOPSIS 

profll(buff,  buMi|  offset,  scale) 
char  ^bufTi 

Int  bufsls,  offset,  scale; 

DESCRIPTION 

Buff  points  to  an  area  of  core  whose  length  (in  bytes)  is  given  by  bufaiz.  After  this  call,  the  user’s 
program  counter  (pc)  is  examined  each  clock  tick  (20  milliseconds);  offset  is  subtracted  from  it, 
and  the  result  multiplied  by  scale.  If  the  resulting  number  corresponds  to  a  word  inside  buff,  that 
word  is  incremented. 

The  scale  is  interpreted  as  an  unsigned,  fixed-point  fraction  with  binary  point  at  the  left:  0x10000 
gives  a  1-1  mapping  of  pc’s  to  words  in  huff;  0x8000  maps  each  pair  of  instruction  words  together. 
0x2  maps  all  instructions  onto  the  beginning  of  6ti^  (producing  a  non-interrupting  core  clock). 

Profiling  is  turned  off  by  giving  a  scale  of  0  or  1.  It  is  rendered  ineffective  by  giving  a  bufsiz  of  0. 
Profiling  is  turned  off  when  an  txeeve  is  executed,  but  remains  on  in  child  and  parent  both  after  a 
fork.  Profiling  is  turned  off  if  an  update  in  would  cause  a  memofy  fault. 

RETURN  VALUE 

A  0,  indtcating  success,  is  always  returned^ 

SEE  ALSO 

gprof(l),  8etitimer(2),  monitor(3) 
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NAME 

ptrace  -  process  trace 
SYNOPSIS 

#inelude  <slgnal«h> 

ptraee(requ€8t,  pld»  addr,  data) 
tnt  requestf  pld^  ^addr^  data; 

DESCRIPTION 

Ptrace  provides  a  means  by  which  a  parent  process  may  control  the  execution  of  a  child  process, 
and  examine  and  change  its  core  image.  Its  primary  use  is  for  the  implementation  of  breakpoint 
debugging.  There  are  four  arguments  whose  interpretation  depends  on  a  rtqneai  argument.  Gen* 
erally,  pid  is  the  process  ID  of  the  traced  process,  which  must  be  a  child  (no  more  distant  descen¬ 
dant)  of  the  tracing  process.  A  process  being  traced  behaves  normally  until  it  encounters  some 
signal  whether  internally  generated  like  ^^illegal  instruction’’  or  externally  generated  like  **intei^ 
rupt”.  See  8igvec{2)  for  the  list.  Then  the  traced  process  enters  a  stopped  state  and  its  parent  is 
notified  via  u;a}7(2).  When  the  child  is  in  the  stopped  state,  its  core  image  can  be  examined  and 
modified  using  ptrace.  If  desired,  another  ptrace  request  can  then  cause  the  child  either  to  ter¬ 
minate  or  to  continue,  possibly  ignoring  the  signal. 

The  value  of  the  request  argument  determines  the  precise  action  of  the  call: 

0  This  request  is  the  only  one  used  by  the  child  process;  it  declares  that  the  process  is  to  be 
traced  by  its  parent.  All  the  other  arguments  are  ignored.  Peculiar  results  will  ensue  if  the 
parent  does  not  expect  to  trace  the  child. 

1,2  The  word  in  the  child  process’s  address  space  at  addr  is  returned.  If  I  and  D  space  are 
separated  (e.g.  historically  on  a  pdp-11),  request  1  indicates  I  space,  2  D  space.  Addr  must  be 
even.  The  child  must  be  stopped.  The  input  data  is  ignored. 

3  The  word  of  the  system’s  per-process  data  area  corresponding  to  addr  is  returned.  Addr  must 
be  even  and  less  than  512.  This  space  contains  the  registers  and  other  information  about  the 
process;  its  layout  corresponds  to  the  user  structure  in  the  ^stem. 

4,5  The  given  data  is  written  at  the  word  in  the  process’s  address  space  corresponding  to  addr, 
which  must  be  even.  No  useful  value  is  returned.  If  I  and  D  space  are  separated,  request  4 
indicates  I  space,  5  D  space.  Attempts  to  write  in  pure  procedure  fail  if  another  process  is 
executing  the  same  file. 

6  The  process’s  system  data  is  written,  as  it  is  read  with  request  3.  Only  a  few  locations  can 
be  written  in  this  way:  the  general  registers,  the  floating  point  status  and  registers,  and  cer¬ 
tain  bits  of  the  processor  status  word. 

7  The  data  argument  is  taken  as  a  signal  number  and  the  child’s  execution  continues  at  loca¬ 
tion  addr  as  if  it  had  incurred  that  signal.  Normally  the  signal  number  will  be  either  0  to 
indicate  that  the  signal  that  caused  the  stop  should  be  ignored,  or  that  value  fetched  out  of 
the  process’s  image  indicating  which  signal  caused  the  stop.  If  addr  is  (int  ^)l  then  execution 
continues  from  where  it  stopped. 

8  The  traced  process  terminates. 

9  Execution  continues  as  in  request  7;  however,  as  soon  as  possible  after  execution  of  at  least 
one  instruction,  execution  stops  again.  The  signal  number  from  the  stop  is  SIGTRAP.  (On 
the  Sun  and  VAX-11  the  T-bit  is  used  and  just  one  instruction  is  executed.)  This  is  part  of 
the  mechanism  for  implementing  breakpoints. 

As  indicated,  these  calls  (except  for  request  0)  can  be  used  only  when  the  subject  process  has 
stopped.  The  wait  call  is  used  to  determine  when  a  process  stops;  in  such  a  case  the  termina¬ 
tion”  status  returned  by  wait  has  the  value  0177  to  indicate  stoppage  rather  than  genuine  termi¬ 
nation. 
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To  forestall  possible  fraud,  ptraee  inhibits  the  set-user^id  and  set-group>id  faeilities  on  subsequent 
execve{2)  calls.  If  a  traced  process  calls  exeeve,  it  will  stop  before  executing  the  first  instruction 
of  the  new  image  showing  signal  SIGTRAP. 

On  the  Sun  and  VAX-11,  “word”  also  means  a  32-bit  integer,  but  the  “even”  restriction  does  not 
apply. 

RETURN  VALUE 

A  0  value  is  returned  if  the  call  succeeds.  If  the  call  fails  then  a  -1  is  returned  and  the  global 
variable  ermo  is  set  to  indicate  the  error. 

ERRORS 

(BINVAL}  The  request  code  is  invalid. 

(EINVAL)  The  specified  process  does  not  exist. 

^INVAL[  The  given  signal  number  is  mvalid. 

[EFAULT]  The  specified  address  &  out  of  bounds. 

[EPERM|  The  specified  process  cannot  be  traced. 

SEE  ALSO 

wait(2),  sigvec(2),  adb(lS) 

BUGS 

Ptraee  is  unique  and  arcane;  it  should  be  replaced  with  a  special  file  which  can  be  opened  and 
read  and  written.  The  control  functions  could  then  be  implemented  with  >ocii(2)  calls  on  this  file. 
This  would  be  simpler  to  understand  and  have  much  higher  performance. 

The  request  0  call  should  be  able  to  specify  signals  which  arc  to  be  treated  normally  and  not 
cause  a  stop.  In  this  way,  for  example,  programs  with  simulated  floating  point  (which  use  “illegal 
instruction”  signals  at  a  very  high  rate)  could  be  efficiently  debugged. 

The  error  indication,  -1,  is  a  legitimate  function  value;  errno,  see  tnfro(2),  can  be  used  to  disam¬ 
biguate. 

It  should  be  possible  to  stop  a  process  on  occurrence  of  a  qrstem  call;  in  this  way  a  completely 
controlled  environment  could  be  provided. 
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NAME 

quota  -  manipulate  disk  quotas 
SYNOPSIS 

#lnclude  <sya/quotndi> 

quota(cmd|  uidf  argy  addr) 
lat  emd)  uld|  arg| 
caddrjt  addr| 

DESCRIPTION 

The  quota  call  manipulates  disk  quotas  for  6te  systems  which  have  had  quotas  enabled  with  set- 
quota{2).  The  cmd  parameter  indicates  a  command  to  be  applied  to  the  user  ID  uid,  Arg  is  a 
command  specific  argument  and  addr  is  the  address  of  an  optionali  command  specific,  data  struc* 
ture  which  is  copied  in  or  out  of  the  system.  The  interpretation  of  arg  and  addr  is  given  with 
each  command  below, 

Q^SETDLIM 

Set  disc  quota  limits  and  current  usage  for  the  user  with  ID  utd,  Arg  is  a  major^minor 
device  indicating  a  particular  file  system.  Addr  is  a  pointer  to  a  struct  dqblk  structure 
(defined  in  Ksyoj quota,h>).  This  call  is  restricted  to  the  super-user. 

Q_GETDLIM 

Get  disc  quota  limits  and  current  usage  for  the  user  with  ID  uiV.  The  remaining  parame* 
tcrs  are  as  for  QJ5ETDLIM. 

Q^SETDUSE 

Set  disc  usage  limits  for  the  user  with  ID  usd.  Arg  is  a  major-minor  device  indicating  a 
particular  file  system.  Addr  is  a  pointer  to  a  struct  dqusage  structure  (defined  in 
<sy8l quota,h>Y  This  call  is  restricted  to  the  super-user. 

Q.SYNC 

Update  the  on-disc  copy  of  quota  usages.  The  uid,  arg,  and  addr  parameters  are  ignored. 
Q^SETUID 

Change  the  calling  processes  quota  limits  to  those  of  the  user  with  ID  md.  The  arg  and 
addr  parameters  are  ignored.  This  call  is  restricted  to  the  super-user. 

Q_SETWARN 

Alter  the  disc  usage  warning  limits  for  the  user  with  ID  uid.  Arg  is  a  major-minor  device 
indicating  a  particular  file  system.  Addr  is  a  pointer  to  a  struct  dqwarn  structure  (defined 
in  <ey8j quota, This  call  is  restricted  to  the  super-user. 

Q^DOWARN 

Warn  the  user  with  user  ID  uid  about  excessive  disc  usage.  This  call  causes  the  system  to 
check  its  current  disc  usage  information  and  print  a  message  on  the  terminal  of  the  caller 
for  each  file  system  on  which  the  user  is  over  quota.  If  the  arg  parameter  is  specified  as 
NODEV,  all  file  systems  which  have  disc  quotas  will  be  checked.  Otherwise,  arg  indicates 
a  specific  major-minor  device  to  be  checked.  This  call  is  restricted  to  the  super-user. 

RETURN  VALUE 

A  successful  call  returns  0  and^  possibly,  more  information  specific  to  the  cmd  performed;  when  an 
error  occurs,  the  value  -1  is  returned  and  errno  b  set  to  indicate  the  reason. 

ERRORS 

A  quota  call  will  fail  when  one  of  the  following  occurs; 

[EINVAL]  Cmd  is  invalid. 

[ESRCH]  No  disc  quota  is  found  for  the  indicated  user. 

[EPERM]  The  call  is  priviledged  and  the  caller  was  not  the  super-user. 
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[EINVAL]  The  arg  parameter  is  being  interpreted  as  a  major-minor  device  and  it  indicates 
an  unmounted  file  system. 

[EFAULT]  An  invalid  addr  is  supplied;  the  associated  structure  could  not  be  copied  in  or 
out  of  the  kernel. 

(EUSERS)  The  quota  table  is  full. 

SEE  ALSO 

setquota(2),  quotaon(S)»  quotacheck($) 

BUGS 

There  should  be  someway  to  integrate  this  call  with  the  resource  limit  interface  provided  by 
8eirHmit{2)  and  getrtimit{2). 

The  Australian  spelling  of  disk  is  used  throughout  the  quota  facilities  in  honor  of  the  implemen¬ 
tors. 
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NAME 

read,  readv  -  read  input 
SYNOPSIS 

ec  read(d9  buf|  nbytea) 

Int  eCt  <t| 
char  ’^bufjt 
lot  nbytesi 

#lncludc  <«ys/typea.h> 

#liietude  <sy«/ulo.h> 

cc  =  readv(dt  lov»  lovcnt) 

Int  eCf  d| 
struct  lovec  ’^tov| 

Int  toventf 

DESCRIPTION 

Read  attempts  to  read  nbyte^  of  data  from  the  object  referenced  by  the  descriptor  d  into  the 
buffer  pointed  to  by  buf.  Readv  performs  the  same  action,  but  scatters  the  input  data  into  the 
iovcnt  buffers  specified  by  the  members  of  the  iovec  array:  iov[0),  iov[l],  iov(iovcnt-lj* 

For  readv,  the  iovec  structure  is  defined  as 

struct  iovec  { 

caddr_t  iov_base; 
int  iovjen; 

}: 

Each  iovec  entry  specifies  the  base  address  and  length  of  an  area  in  memoiy  where  data  should  be 
placed.  Readv  will  always  fill  an  area  completely  before  proceeding  to  the  next. 

On  objects  capable  of  seeking,  the  read  starts  at  a  position  given  by  the  pointer  associated  with  d, 
see  heek{2).  Upon  return  from  read,  the  pointer  is  incremented  by  the  number  of  bytes  actually 
read. 

Objects  that  are  not  capable  of  seeking  always  read  from  the  current  position.  The  value  of  the 
pointer  associated  with  such  a  object  is  undefined. 

Upon  successful  completion,  read  and  readv  return  the  number  of  bytes  actually  read  and  placed 
in  the  buffer.  The  system  guarantees  to  read  the  number  of  bytes  requested  if  the  descriptor 
references  a  file  which  has  that  many  bytes  left  before  the  end-of-file,  but  in  no  other  cases. 

If  the  returned  value  is  0,  then  end-of-file  has  been  reached. 

RETURN  VALUE 

If  successful,  the  number  of  bytes  actually  read  is  returned.  Othewise,  a  -1  is  returned  and  the 
global  variable  errno  is  set  to  indicate  the  error. 

ERRORS 

Read  and  resdu  will  fail  if  one  or  more  of  the  following  are  true: 

[EBADF]  Fitdes  is  not  a  valid  file  descriptor  open  for  reading. 

(EFAULTj  Buf  points  outside  the  allocated  address  space. 

[EINTR]  A  read  from  a  slow  device  was  interrupted  before  any  data  arrived  by  the 

delivery  of  a  signal. 

In  addition,  readv  may  return  one  of  the  following  errors: 

[EINVAL]  lovcnt  was  less  than  or  equal  to  0,  or  greater  than  16. 

[EINVAL]  One  of  the  iovjlen  values  in  the  iov  array  was  negative. 

[EINVALj  The  sum  of  the  iovjlen  values  in  the  iov  array  overflowed  a  32-bit  integer. 
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SEE  ALSO 

<iup(2)>  opeii(2)»  pipe(2),  60cket(2),  80cketpair(2) 
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NAME 

readlink  -  read  value  of  a  embolic  link 


SYNOPSIS 

ee  ss  readUiik(path,  btif,  bufslx) 
int  cc} 

char  *path,  *bttfi 
Int  buftls; 

DESCRIPTION 

Readlink  places  the  contents  of  the  symbolic  link  name  in  the  buffer  bttf  which  has  size  bufsiz. 
The  contents  of  the  link  are  not  null  terminated  when  returned. 

RETURINI  VALUE 

The  call  returns  the  count  of  characters  placed  in  the  buffer  if  it  succeeds,  or  a  -1  if  an  error 
occurs,  placing  the  error  code  in  the  global  variable  errno. 


ERRORS 

Readlink  will  fail  and  the  file  mode  will  be  unchanged  if; 


{EPERMj 

[ENOENT] 

jENOTDIRl 

lENOENT] 

(ENXIOJ 

lEACCES) 

|EPERM| 


The  path  argument  contained  a  byte  with  the  high>order  bit  set. 

The  pathname  was  too  long. 

A  component  of  the  path  prefix  b  not  a  directory. 

The  named  file  does  not  exbt. 

The  named  file  b  not  a  symbolic  link. 

Search  permbsion  is  denied  on  a  component  of  the  path  prefix. 

The  effective  user  ID  does  not  match  the  owner  of  the  file  and  the  effective  user 
ID  b  not  the  super-user. 


(EINVAL)  The  named  file  b  not  a  symbolic  link. 

[EFAULT]  Buf  extends  outside  the  process's  allocated  address  space. 

|ELOOP]  Too  many  symbolic  links  were  encountered  in  translating  the  pathname. 

SEE  ALSO 

8tat(2),  btat(2),  symiink(2) 
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NAME 

reboot  —  reboot  system  or  halt  processor 
SYNOPSIS 

#lneluda  <ay«/r«boot.h> 

reboot(howto) 

Int  howtot 

DESCRIPTION 

Reboot  reboots  the  system,  and  is  invoked  aut<MnaticaIly  in  the  event  of  unrecoverable  system 
failures.  Howto  is  a  mask  of  options  passed  to  the  bootstrap  program.  The  system  call  interface 
permits  only  RB_HALT  or  RB_AUTOBOOT  to  be  passed  to  the  reboot  program;  the  other  flags 
are  used  in  scripts  stored  on  the  console  storage  media,  or  used  in  manual  bootstrap  procedures. 
When  none  of  these  options  (e.g.  BB_AUTOBOOT)  is  given,  the  system  is  rebooted  from  file 
"vmunix”  in  the  root  file  system  of  unit  0  of  a  disk  chosen  in  a  processor  specific  way.  An 
automatic  consistency  check  of  the  disks  is  then  normally  performed. 

The  bfts  of  howto  are: 

RBJIALT 

the  processor  is  simply  halted;  no  reboot  takes  place.  RBJIALT  should  be  used  with 
caution. 

RBJ^SKNAME 

Interpreted  by  the  bootstrap  program  itself,  causing  it  to  inquire  as  to  what  file  should  be 
booted.  Normally,  the  system  is  booted  from  the  file  “vmunix”  without  asking. 

RB_SINGLE 

Normally,  the  reboot  procedure  involves  an  automatic  disk  consistency  check  and  then 
multi-user  operations.  RB_SINGLE  prevents  the  consistency  check,  rather  simply  boot¬ 
ing  the  system  with  a  single-user  shell  on  the  console.  RB.SINGLE  is  interpreted  by  the 
init{6}  program  in  the  newly  booted  system.  This  switch  is  not  available  from  the  system 
call  interface. 

Only  the  super-user  mtgr  reboot  a  machine. 

RETURN  VALUES 

If  successful,  this  call  never  returns.  Otherwise,  a  -1  is  returned  and  an  error  is  returned  in  the 
global  variable  errno. 

ERRORS 

[EPERKlQ  The  caller  is  not  the  super-user. 

SEE  ALSO 

erash(8S),  halt(8),  init(8),  reboot(8) 
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NAME 

recv,  recvfrom,  recvmsg  -  receive  a  message  from  a  socket 
SYNOPSIS 

#include  <sya/typeB.li> 

#include  <pyB/«oeket.h> 

cc  =  recv(8t^  buf,  lent  flftgs) 

Int  ce, 
char  "^bufi 
int  len»  flags; 

cc  =  recvfirom(st  bufy  len^  flagSi  flromt  fromlen) 

Int  CC|  s| 

char  *buf; 

int  ien,  flags; 

struct  sockaddr  "^om; 

int  ^omlen; 

cc  sss  recvm8g(s,  msg^  flags) 
int  cc,  s; 

struct  msghdr  msgQ; 
int  flags; 


DESCRIPTION 

JR  rev,  recvfrom,  Md  rrcvmri?  are  used  to  receive  messages  from  a  socket. 

The  recv  call  may  be  used  only  on  a  connected  socket  (see  connec^(2)),  while  recvfrom  and 
recvmog  may  be  used  to  receive  data  on  a  socket  whether  it  is  in  a  connected  state  or  not. 

If  from  is  non-zero,  the  source  address  of  the  message  is  filled  in.  Fromlen  is  a  value^result 
parameter,  initialized  to  the  size  of  the  buffer  associated  with  from,  and  modified  on  return  to 
indicate  the  actual  size  of  the  address  stored'  there;  The  length  of  the  message  is  returned  in  cc. 
If  a  message  is  too  long  to  fit  in  the  supplied  buffer,  excess  bytes  may  be  discarded  depending  on 
the  type  of  socket  the  message  is  received  from;  see  socket{2). 

If  no  messages  are  available  at  the  socket,  the  receive  call  waits  for  a  message  to  arrive,  unless  the 
socket  is  nonblocking  (see  tec//(2))  in  which  case  a  cc  of -1  is  returned  with  the  external  variable 
errno  set  to  EWOULDBLOCK. 


The  $elect(2)  call  may  be  used  to  determine  when  more  data  arrives. 

The  flags  argument  to  a  send  call  is  formed  by  er’ing  one  or  more  of  the  values, 

#define  MSG  J^EEK  0x1  f*  peek  at  incoming  message  */ 

#define  MSG^OOB  0x2  /*  process  out*of-band  data  */ 

The  recvmsg  call  uses  a  msghdr  structure  to  minimize  the  number  of  directly  supplied  parameters. 
This  structure  has  the  fofiowing  form,  as  defined  in  <sgsjsocket,h>\ 


struct  msghdr  { 

caddrjt  msg^name; 
int  msg^namelen; 
struct  iovec  •msg^iov; 
int  msg^iovlen; 
caddr_t  msg^accrights; 
int  msg.accrightslen; 


/♦  optional  address  */ 

/*  size  of  address  ♦/ 

/♦  scatter/gather  array  */ 

#  elements  in  msg^iov 
/*  access  rights  sent/received  */ 


Here  msg_name  and  msgjnamelen  specify  the  destination  address  if  the  socket  is  unconnected; 
msgjaame  may  be  given  as  a  null  pointer  if  no  names  are  desired  or  required.  The  msgjiov  and 
msgjiovien  describe  the  scatter  gather  locations,  as  described  in  read(2).  Access  rights  to  be  sent 
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along  with  the  message  are  specified  in  Ttug_iiecright8,  which  has  length  m8g_accrigkt8ten. 

return  value 

These  calls  return  the  number  of  bytes  received,  or  -1  if  an  error  occurred. 

ERRORS 

The  calls  fail  if: 

|EBADF}  The  argument  s  is  an  invalid  descriptor. 

(ENOTSOCK]  The  argument  8  is  not  a  socket. 

(EWOULDBLOCK)  The  socket  is  marked  non>blocking  and  the  receive  operation  would  block. 

{EINTR)  The  receive  was  interrupted  by  delivery  of  a  signal  before  any  data  was 

available  for  the  receive. 

jEFAULT)  The  data  was  specified  to  be  received  into  a  non-existent  or  protected  part 

of  the  process  agrees  space. 

SEE  ALSO 

read(2),  8end(2),  Boeket(2) 
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NAME 

rename  —  change  the  name  of  a  file 

SYNOPSIS 

rename(froni|  to) 
char  *tTomf  Hoi 

DESCRIPTION 

Renamt  causes  the  link  named  from  to  be  renamed  as  to^  If  to  exists,  then  it  is  first  removed. 
Both  from  and  to  must  be  of  the  same  type  (that  is,  both  directories  or  both  non-directories),  and 
must  reside  on  the  same  file  system. 

Rename  guarantees  that  an  instance  of  to  will  always  exist,  even  if  the  system  should  crash  in  the 
middle  of  the  operation. 

CAVEAT 

The  system  can  deadlock  if  a  loop  In  the  file  system  graph  is  present.  This  loop  takes  the  form  of 
an  entry  in  directory  “a”,  say  **a/foo*’,  being  a  hard  link  to  directory  *‘b'’,  and  an  entry  in  direc¬ 
tory  say  *'b/bar*^  being  a  hard  link  to  directory  ''a**.  When  such  a  loop  exists  and  two 
separate  processes  attempt  to  perform  ‘‘rename  a/foo  b/bar**  and  “rename  b/bar  a/foo“,  respec¬ 
tively,  the  system  may  deadlock  attempting  to  lock  both  directories  for  modification.  Hard  links 
to  directories  should  be  replaced  by  symbolic  links  by  the  ^stem  administrator. 

RETURN  VALUE 

A  0  value  is  returned  if  the  operation  succeeds,  otherwise  rename  returns  -1  and  the  global  vari* 
able  errno  indicates  the  reason  for  the  failure. 


ERRORS 

Rename  will  fail  and  neither  of  the  argument  files  will  be  affected  if  any  of  the  following  are  true: 


(ENOTDIRl 

[ENOENTI 

(EACCESj 

(ENOENTI 

(EPERMl 

(EXDEV) 

(EACCESJ 

(EROFS) 

(EFAULT) 

(EINVAL) 

SEE  ALSO 

open(2) 


A  component  of  either  path  prefix  is  not  a  directory. 

A  component  of  either  path  prefix  does  not  exbt. 

A  component  of  either  path  prefix  denies  search  permission. 

The  file  named  by  from  docs  not  exist. 

The  file  named  by  from  is  a  directory  and  the  effective  user  ID  is  not  super-user. 

The  link  named  by  to  and  the  file  named  by  from  are  on  different  logical  devices 
(file  systems).  Note  that  this  error  code  will  not  be  returned  if  the  implementa¬ 
tion  permits  cross-device  links. 

The  requested  link  requires  writing  in  a  directory  with  a  mode  that  denies  write 
permission. 

The  requested  link  requires  writing  in  a  directory  on  a  read-only  file  system. 

Path  points  outside  the  processes  allocated  address  space. 

From  is  a  parent  directory  of  to. 
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RMDIR(2) 


SYSTEM  CALLS 


RMDIR(2) 


NAME 

ttndir  -  remove  a  directory  file 

SYNOPSIS 

rmdlr^ath) 
char  "'pathi 

DESCRIPTION 

Rmdir  removes  a  directory  file  whose  name  is  given  by  path.  The  directory  must  not  have  any 
entries  other  than  and 

RETURN  VALUE 

A  0  is  returned  if  the  remove  succeeds;  otherwise  a  -1  is  returned  and  an  error  code  is  stored  in 
the  global  location  errno . 

ERRORS 

The  named  file  is  removed  unless  one  or  more  of  the  following  are  trsM: 

[ENOTEMPTY]  The  named  directory  contains  files  other  than  ‘V’  and  in  it. 

(EPERh^  The  pathname  contains  a  character  with  the  high>oader  bit  set. 

[ENOENT]  The  pathname  was  too  long. . 

[ENOTDIRl^  A  component  of  the  path  prefix  is  not  a  dwectoiy. 

(ENOENTj  The  named  file  does  not  exist. 

(EACCES)  A  component  of  the  path  prefix  dentes  search  perrafemn. 

(EACCES]  Write  permission  is  denied  on  the  directoty  containfeg.  the  link  to  be  removed. 
(EBUSY)  The  directory  to  be  removed  is  the  mount  point  for  a  mounted  file  system. 

(EROPS|  The  directory  entry  to  be  removed  resides  on  a  read«only  file  system. 

(EFAULT]  Path  points  outside  the  process's  allocated  address  space. 

[ELOOP]  Too  many  symbolic  links  were  encountered  in  tran8btiag.the  pathname. 

SEE  ALSO 

mkdir(2),  unlink(2) 
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SELECT(2) 


SYSTEM  CALLS 


SELECT(2) 


NAME 

select  -  synchronous  I/O  multiplexing 
SYNOPSIS 

#lnclude  <Bys/time.h> 

nfdi  —  Belect(widtht  readfdB^  wrltefds,  cxeeptfdBf  timeout) 

Int  width,  ^readfdi,  *wrltefdB,  ^execptfdB) 

Btruet  timeval  ^timeouti 

DESCRIPTION 

Select  examines  the  I/O  descriptors  specified  by  the  bit  masks  reatffds,  writefda,  and  exeeptfds  to 
sec  if  they  are  ready  for  reading,  writing,  or  have  an  exceptional  condition  pending,  respectively. 
Width  is  the  number  of  significant  bits  in  each  bit  mask  that  represent  a  file  descriptor.  Typically 
width  has  the  value  returned  by  geidtablesize  (2)  for  the  maximum  number  of  file  descriptors  or  is 
the  constant  32  (number  of  bits  in  an  int).  File  descriptor  /  is  represented  by  the  bit  “l<<r’  in 
the  mask.  Select  returns,  in  place,  a  mask  of  those  descriptors  which  are  ready.  The  total 
number  of  ready  descriptors  is  returned  in  nfde. 

If  timeout  is  a  non-zero  pointer,  it  specifies  a  maximum  interval  to  wait  for  the  selection  to  com¬ 
plete.  If  timeout  is  a  zero  pointer,  the  select  blocks  indefinitely.  To  effect  a  poll,  the  timeout 
argument  should  be  non-zero,  pointing  to  a  zero  valued  timeval  structure. 

Any  of  readfde,  writefde,  and  exeeptfds  may  be  given  as  0  if  no  descriptors  are  of  interest. 
RETURN  VALUE 

Select  returns  the  number  of  descriptors  which  are  contained  in  the  bit  masks,  or  -*1  if  an  error 
occurred.  If  the  time  limit  expires  then  select  returns  0. 

ERRORS 

An  error  return  from  select  indicates: 

[EBADF]  One  of  the  bit  masks  specified  an  invalid  descriptor. 

[EINTR]  An  signal  was  delivered  before  any  of  the  selected  events  occurred  or  the  time 

limit  expired. 

SEE  ALSO 

accept(2),  connect(2),  gettimeofday(2),  read(2),  write(2),  recv(2),  send(2),  getdtablesize(2) 

BUGS 

The  descriptor  masks  are  always  modified  on  return,  even  if  the  call  returns  as  the  result  of  the 
timeout. 
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SEND  (2) 


SYSTEM  CALLS 


SEND  (2) 


o 


NAME 

send,  sendto,  sendinsg  -  send  a  message  from  a  socket 
SYNOPSIS 

#liielude  <8ys/type8.h> 

#lnclude  <8yB/80cket.h> 

ee  sst  Bend(8»  mag,  len,  flags) 

Int  ce,  8) 
char  *in8g) 

Ipt  len,  flags) 

tc  =  8endto(s«  msg,  len,  flags,  to,  tolen) 

Ift  CC,  8) 

l^har  *m8g) 
len,  flags) 

struct  sockaddr  'Ho) 
t^t  tolen) 

ee  m  sendmsg(8,  msg,  flags) 

Lat  ee,  s) 

struct  msghdr  xnsgQt 
Int  flags) 

DESCRIPTION 

5>  is  a  socket  created  with  aoeket{2).  Seni^,  aendto,  and  atndmag  are  «sed-to  traasmit  a  message  to 
another  socket.  Send  may  be  used  only  when  the  socket  fs  in  a  co  nnecfed  state,  while  aendti)  and 
eendmag  may  be  used  at  any  time. 

The  address  of  the  target  is  given  by  to  with  tolen  specifying  its  size.  The  length  of  the  message 
is  given  by  len.  If  the  message  is  too  tong  to  pass  atomically  through  the  underlying  protocol, 
then  the  error  EMSGSIZE  is  returned,  and  the  message  is  not  transmitted. 

No  indication  of  failure  to  deliver  is  implicit  in  a  send.  Return  values  of  -1  indicate  some  locally 
detected  errors. 

If  no  messages  space  is  available  at  the  socket  to  hold  the  message  to  be  transmitted,  then  send 
normally  blocks,  unless  the  socket  has  been  placed  in  non-blocking  i/o  mode.  The  oelect(2)  call 
may  be  used  to  determine  when  it  is  possible  to  send  more  data. 

The  flago  parameter  may  be  set  to  SOP_OOB  to  send  ‘*out-of-band”  data  on  sockets  which  sup¬ 
port  this  notion  (e.g.  SOCK^STREAM). 

See  rectf(2)  fo^  a  description  of  the  msghdr  structure. 

RETURN  VALUE 

The  call  returns  the  number  of  characters  sent^  or  -i  if  an  error  oecucred. 


ERRORS 

(EBADFf 

(ENOTSOCK} 

lEPAULT] 

[EMSGSIZE] 

[EWOULDBLOCK] 


An  invalid  descriptor  was  specified. 
The  argument  s  u  not  a  socket. 


An  invalid  user  space  address  was  specified 

The  socket  requires  that  message  be  sent 
message  to  be  sent  made  this  impossible. 


The  socket  is  marked  boh-blocking  and 
block. 


for  a  parameter, 
atomically,  and  the  size 

the  requested  operation 


of  the 
would 


SEE  ALSO 

recv(2),  sbcket(^) 


o 
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SETGR0UPS(2) 


SYSTEM  CALLS 


SETGROUPS(2) 


NAME 

setgroups  -  set  group  access  list 
SYNOPSIS 

#inelude  <Bys/pa:ram«h> 

BetgroupB(ngroupe»  gidset) 

Int  ngroupB,  *gldBet| 

DESCRIPTION 

Seigroupa  sets  the  group  access  list  of  the  current  user  process  according  to  the  array  gidset.  The 
parameter  ngroups  indicates  the  number  of  entries  in  the  array  and  must  be  no  more  than 
NGRPS,  as  defined  in  <$y$/paratn.h>. 

Only  the  super-user  may  set  new  groups. 

RETURN  VALUE 

A  0  value  is  returned  on  success,  -1  on  error,  with  a  error  code  stored  in  errno. 

ERRORS 

The  actgroupa  call  will  fail  if: 

[EPERM]  The  caller  is  not  the  super-user. 

(EFAULT]  The  address  specified  for  gideet  is  outside  the  process  address  space. 

SEE  ALSO 

getgroup8(2),  initgroup8(3) 


o 
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SETPGRP(2) 


SYSTEM  CALLS 


SETPGRP(2) 


NAME 

setpgrp  -  Bet  process  group 

SYNOPSIS 

Betpgrp(pld,  pgi-p) 
tnt  pld,  pgrpi 

DESCRIPTION 

Setp^Tp  sets  the  process  group  of  the  specified  process  pid  to  the  specified  pgrp.  If  pid  is  zero^  then 
the  call  applies  to  the  current  process. 

If  the  involter  is  not  the  super-user,  then  the  affected  process  must  have  the  same  effective  user-id 
as  the  invoker  or  be  a  descendant  of  the  invoking  process^ 

RETURN  VALUE 

Setpgrp  returns  when  the  operation  was  successful.  If  the  request  (aDed,  -1  is  returned  and  the 
global  variable  errno  indicates  the  reason* 

EIRRORS 

5e<pgr]^witl  fail  and  the  process  group  will  not  be  altered  if  one  of  the  following. occur: 

[ESRCH[  The  requested  process  does  not  exist. 

[EPERMj  The  effective  user  ID  of  the  requested  process  is  different  from  that  of  the  caller 

and  the  process  is  not  a  descendent  of  the  calling  process* 

SEE  ALSO 

getpgrp(2> 


o 


o 
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SETQU0TA(2) 


SYSTEM  CALLS 


SETQUOTA(2) 


NAME 

setquota  -  enable/disable  quotas  on  a  file  system 
SYNOPSIS 

8etquota(8peciaJ|  file) 
char  '^8pectal,  *file| 

DESCRIPTION  ^  ^  . 

Disc  quotas  are  enabled  or  disabled  with  the  Bctquota  calL  Special  indicates  a  block  special  device 
on  which  a  mounted  file  system  exists.  If  file  is  nonzero,  it  specifies  a  file  in  that  file  system  from 
which  to  take  the  quotas.  If  file  is  0,  then  quotas  are  disabled  on  the  file  system.  The  quota  file 
must  exist;  it  is  normally  created  with  the  quclacheek[S)  program. 

Only  the  super-user  may  turn  quotas  on  or  off. 

SEE  ALSO 

quota(2),  quotacheck(8),  quotaon(8) 

RETURN  VALUE 

A  0  return  value  indicates  a  successful  call.  A  value  of  —1  is  returned  when  an  error  occurs  and 
errno  is  set  to  indicate  the  reason  for  failure. 

ERRORS 

Selquota  will  fail  when  one  of  the  following  occurs: 

(NODEV)  The  caller  is  not  the  super-user. 

[NODEV]  Special  does  not  exist. 

jENOTBLKl  Special  is  not  a  block  device. 

jENXIOj  The  major  device  number  of  special  is  out  of  range  (this  indicates  no  device 

driver  exists  for  the  associated  hardware). 

(EPERM)  The  pathname  contains  a  character  with  the  high-order  bit  set. 

[ENOTDIR]  A  component  of  the  path  prefix  in  file  is  not  a  directory. 

lEROFSj  File  resides  on  a  read-only  file  system. 

[E^CCES]  File  resides  on  a  file  system  different  from  special. 

(EACCES]  File  is  not  a  plain  file. 

BUGS 

The  error  codes  are  in  a  state  of  disarray;  too  many  errors  appear  to  the  caller  as  one  value. 


82 


Last  change:  29  August  1983 


Sun  Release  1,1 


SBTREGID(2) 


SYSTEM  CALLS 


SETREGID(2) 


NAME 

setKgid  -  set  real  and  effective  group  ID 

SYNOPSIS 

aetr«gid(rgld,  egld) 

Int  rgid,  egld; 

DESCRIPTION 

The  real  and  effective  group  ID’s  of  the  current  process  are  set  to  the  arguments.  Only  the 
super'User  may  change  the  real  group  ID  of  a  process.  Unpriviledged  users  may  change  the 
effective  group  ID  to  the  real  group  ID,  but  to  no  other. 

Supplying  a  value  of  -1  for  either  the  real  or  effective  group  ID  forces  the  system  to  substitute  the 
current  ID  in  place  of  the  -1  parameter, 

RETURN  VALUE 

Upon  successful  completion,  a  value  of  0  is  returned.  Otherwise,  »  value  of  -1  is  returned  and 
errno  is  set  to  indicate  the  error. 

ERRORS 

[BPERh^  The  current  process  is  not  the  super^user  and  a  change  other  than  changing  the 
effective  group-id  to  the  real  group-id  was  specified. 

SEEALSO 

getgid(2),  setreuid(2)^  8etgid(3C) 


o 
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SETREUID  (2) 


SYSTEM  CALLS 


SETREUID(2) 


NAME 

setreuid  -  set  real  aad  effective  user  ID ^8 

SYNOPSIS 

setreutd(ruld,  euld) 
int  ruidi  euld| 

DESCRIPTION 

The  real  and  effective  user  ID’s  of  the  current  process  are  set  according  to  the  arguments.  If  ruid 
or  euid  is  -1,  the  current  uid  is  filled  in  by  the  system.  Only  the  super-user  may  modify  the  real 
uid  of  a  process.  Users  other  than  the  super-user  may  change  the  effective  uid  of  a  process  only  to 
the  real  uid. 

RETURN  VALUE 

Upon  successful  completion,  a  value  of  0  is  returned.  Otherwise,  a  value  of  -1  is  returned  and 
errno  is  set  to  indicate  the  error. 

ERRORS 

[EPERMj  The  current  process  is  not  the  super-user  and  a  change  other  than  changing  the 

effective  user-id  to  the  real  user-id  was  specified. 

SEE  ALSO 

getuid(2),  setregid(2),  setuid(3) 
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SHUTD0WN(2) 


SYSTEM  CALLS 


SHUTDOWN!  2) 


NAME 

shutdown  -  shut  down  part  of  a  full-duplex  connectioa 

SYNOPSIS 

Bhutdown(8»  how) 

Int  8»  how| 

DESCRIPTION 

The  Bhiitdown  call  causes  all  or  part  of  a  full-duplex  connection  on  the  socket  associated  with  e  to 
be  shut  down.  If  how  is  0,  then  further  receives  wiH  be  disallowed.  If  how  is  1,  then  further  sends 
will  be  disallowed.  If  how  is  2,  then  farther  sends  and  receives  will  be  disallowed. 

DIAGNOSTICS 

A  0  is  returned  if  the  call  succeeds,  -1  if  it  fails. 

ERRORS 

The  call  succeeds  unless: 

[EBADF]  S  is  not  a  valid  deaerator. 

lENOTSOCKj  5l6afile,  notasocket.- 
(ENOTCONN).  The  specified  socket  is  not  connected. 

SEE  ALSO 

connect!^,  80cket(2) 

BUGS 

The  Aotv  values  should  be  defined  constants. 


Sun  Release  I.l 


Last  change:  29  August  1983 


85 


SIGBLOCK(2) 


SYSTEM  CALLS 


SIGBLOCK(2) 


NAME 

Bigblock  -  block  signals 
SYNOPSIS 

oldmask  —  8lgblock(inaBk)| 

Int  maski 

DESCRIPTION 

Sigbhck  adds  the  signals  specified  in  mask  to  the  set  of  signab  currently  being  blocked  from 
delivery.  Signal  i  b  blocked  if  the  i-l*th  bit  in  maek  is  a  1.  The  previous  mask  b  returned,  and 
may  be  restored  using  $igsetma$k{2). 

It  is  not  possible  to  block  SICKILL,  SIGSTOP,  or  SIGCONT;  thb  restriction  is  silently  imposed 
by  the  system. 

RETURN  VALUE 

The  previous  set  of  masked  signals  b  returned. 

SEE  ALSO 

kiii(2),  6igvec(2),  8igsetma8k(2), 
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SIGPAUSE(2) 


SYSTEM  CALLS 


SIGPAUSE(2) 


NAME 

sigpauae  -  atomically  release  blocked  signals  and  wait  for  interrupt 

SYNOPSIS 

8lgpause(6lgmaak) 

Int  aigmaiki 

DESCRIPTION 

Sigpautt  assigns  tigmatk  to  the  set  of  masked  signals  and  then  waits  for  a  signal  to  arrive;  on 
return  the  set  of  masked  signals  is  restored.  Sigmask  is  usually  0  to  indicate  that  no  signals  are 
now  to  be  blocked.  Sigpaude  alwsys  terminates  by  being  interrupted,  returning  EINTR. 

In  normal  usage,  a  signal  is  blocked  using  eigbloek{2),  to  begin  a  critical  section,  variables 
modified  on  the  occurance  of  the  signal  are  examined  to  determine  that  there  is  no  work  to  be 
dene,  and  the  process  pauses  awaiting  work  by  using  digpause  with  the  mask  returned  by  ngbloek. 

SEE  ALSO 

8igbloek(2),  8igvec(2) 


Sun  Release  1.1 


Last  change:  7  July  1983 


87 


SIGSETMASK(2) 


SYSTEM  CALLS 


SIGSETMASK(2) 


NAME 

sigsetmask  -  set  curreut  signal  mask 

SYNOPSIS 

•IgBetmask(mask)} 
int  mask} 


DESCRIPTION^ sets  the  current  signal  mask  (those  signals  which  arc  blocked  from  delivery).  Signal  t 
is  blocked  if  the  f-l'th  bit  in  matk  is  a  1. 

The  system  quietly  disallows  SIGKILL,  SIGSTOP,  or  SIGCONT  to  be  blocked. 

RETURN  VALUE 

The  previous  set  of  masked  signals  is  returned. 


SEE  ALSO 

kill(2),  sigvec(2),  sigblock(2),  eigpause(2) 
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SIGSTACK(2) 


SYSTEM  CALLS 


SIGSTACK(2) 


NAME 

sigstack  -  set  and/ot  get  signal  stack  context 
SYNOPSIS 

#lnelud«  <atgnal.h> 

struct  sigstaek  { 

caddrjt  H_8p( 

Int  MjDnstaeki 

}l 

algatack(u,  om) 
struct  slgStACk  *88,  *088| 

DESCRIPTION 

Sigttttck  allows  users  to  define  an  alternate  stack  on  which  sfgnals  are  to  be  processed.  If  8»  is- 
neU'Zero,  it  specifies  a  stgnsf  ttack  on  which  to  deliver  signals  and  tells  the  system  if  the  process  is 
currently  executing  on  that  stack.  When  a  signal’s  action  indicates  its  handler  should  execute  on 
the  signal  stack  (specified  with  a  8igvec{2)  call),  the  ^stem  checks  to  see  if  the  process  is 
currently  executing  on  that  stack.  If  the  process  is  not  currently  executing  on  the  signal  stack, 
the  system  arranges  a  switch  to  the  signal  stack  for  the  duration  of  the  signal  handler’s  execution. 
If  088  is  noU'Zero,  the  current  signal  stack  state  is  returned. 

NOTES  '  'll 

Signal  stacks  are  not^  ’’grown”  automatically,  m  is  done  for  the  normal  stack.  If  the  stack 
overflows  unpredictable  results  may  occur. 

RETURN  VALUE 

Upon  successful  completion,  a  value  of  0  is  returned.  Otherwise,  a  value  of  -1  is  returned  and 
errno  is  set  to  indicate  the  error. 


ERRORS 

Sig8taek  will  fail  and  the  signal  stack  context  will  remain  uhchaiiged  if  one  of  the  following 
occurs. 


(^AULT| 


Either  ss  or  eoo  points  to  memory  which  is  not  a  valid  part  of  the  process 
address  space. 


SEE  ALSO 

sigvee(2),  8etjmp(3)  ' 
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SIGVEC(2) 


SYSTEM  CALLS 


SIGVEC(2) 


NAME 

sigvec  -  software  signal  facilities 
SYNOPSIS 

#lnelud«  <8lgnal.h> 

struct  slgvee  { 

lot  (*8v_handler)0l 

Int  sv^maski 

lot  sv_onstaekf 

}l 

Blgvee(sigy  vce,  ov«c) 

Int  stg| 

struct  slgvee  *vaet  '^ovecf 
DESCRIPTION 

The  system  defines  a  set  of  signals  that  may  be  delivered  to  a  process.  Signal  delivery  resembles 
the  occurence  of  a  hardware  interrupt:  the  signal  is  blocked  from  further  occurrence,  the  current 
process  context  is  saved,  and  a  new  one  is  built.  A  process  may  specify  a  handler  to  which  a  sig¬ 
nal  is  delivered,  or  specify  that  a  signal  is  to  be  blocked  or  ignored.  A  process  may  also  specify 
that  a  default  action  is  to  be  taken  by  the  system  when  a  signal  occurs.  Normally,  signal 
handlers  execute  on  the  current  stack  of  the  process.  This  may  be  changed,  on  a  pei^handler 
basis,  so  that  signals  are  taken  on  a  special  eignal  etaek. 

All  signals  have  the  same  priority.  Signal  routines  execute  with  the  signal  that  caused  their  invo¬ 
cation  blocked^  but  other  signals  may  yet  occur.  A  global  signal  maek  defines  the  set  of  signals 
currently  blocked  from  delivery  to  a  process.  The  signal  mask  for  a  process  is  initilized  from  that 
of  its  parent  (normally  0).  It  may  be  changed  with  a  $igbloek{2)  or  eigsetmaik{2)  call,  or  when  a 
signal  is  delivered  to  the  process. 

When  a  signal  condition  arises  for  a  process,  the  signal  is  added  to  a  set  of  signals  pending  for  the 
process.  If  the  signal  is  not  currently  blocked  by  the  process  then  it  is  delivered  to  the  process. 
When  a  signal  is  delivered,  the  current  state  of  the  process  is  saved,  a  new  signal  mask  is  calcu¬ 
lated  (as  described  below),  and  the  signal  handler  is  invoked.  The  call  to  the  handler  is  arranged 
so  that  if  the  signal  handling  routine  returns  normally  the  process  will  resume  execution  in  the 
context  from  before  the  signars  delivery.  If  the  process  wishes  to  resume  in  a  different  context, 
then  it  must  arrahge  to  restore  the  previous  context  itself. 

When  a  signal  is  deliverifd  to  a  process  a  new  signal  mask  is  installed  for  the  duration  of  the  pro¬ 
cess*  signal  handler  (or  until  a  eigbtock  or  eigaetmaek  coSi  is  made).  This  mask  is  formed  by  taking 
the  current  signal  mask,  adding  the  signal  to  be  delivered,  and  or*ing  in  the  signal  mask  associ¬ 
ated  with  the  handler  to  be  invoked. 

Sigvec  assigns  a  handler  for  a  specific  signal.  If  vec  is  non-zero,  it  specifies  a  handler  routine  and 
mask  to  be  used  ,  when  delivering  the  specified  signal.  Further,  if  ev^onetack  is  1,  the  system  will 
deliver  the  signal  to  the  process  on  a  eignal  stack,  specified  with  sigetack{2).  If  ovec  is  non-zero, 
the  previous  handling  information  for  the  signal  is  returned  to  the  user. 

The  following  is  a  list  of  all  signals  with  names  as  in  the  include  file  <st^a/.h>: 


SIGHUP 

1 

hangup 

SIGINT 

2 

interrupt 

SIGQUIT 

3* 

quit 

SIGILL 

4* 

illegal  instruction 

SIGTRAP 

5* 

trace  trap 

SIGIOT 

6* 

lOT  instruction 

SIGEMT 

7* 

EMT  instruction 

SIGFPE 

8* 

floating  point  exception 

SIGKILL 

9 

kilt  (cannot  be  caught,  blocked,  or  ignored) 
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SIGBUS 

10* 

SIGSEGV 

11* 

SIGSYS 

12* 

SIGPIPE 

13 

SIGALRM 

14 

SIGTERM 

15 

SIGURG 

16 

SIGSTOP 

17t 

SIGTSTP 

18t 

^IGCONT 

lOs 

jSIGCHLD 

20t 

gliGTTIN 

21t 

SIGTTOU 

22t 

SIGIO 

23 

SIGXCPU 

24 

SIGXFSZ 

25 

SIGVTALRM  26 

SIGPROF 

27 

SIGWINCH 

28 

bus  error 

segmentation  violation 
bad  argument  to  system  call 
write  on  a  pipe  with  no  one  to  read  it 
alarm  clock 

software  termination  signal 
urgent  condition  present  on  socket 
stop  (cannot  be  caught,  blocked,  or  ignored) 
stop  signal  generated  from  keyboard 
continue  after  stop  (cannot  be  blocked) 
child  status  has  changed 

background  read  attempted  from  control  terminal 
background  write  attempted  to  control  terminal 
i/b  is  possible  on  a  descriptor  (see  /cni/(2)) 
cpu  time  limit  exceeded  (see  9etrlimit{2)) 
file  size  limit  exceeded  (see  eetrtimit{2)) 
virtual  time  alarm  (see  eetitimer{2)) 
profiling  timer  alarm  (see  9ctitimer{2)) 
window  changed  (see  W}n(4S)) 


The  starred  signals  in  the  list  above  cause  a  core  image  if  not  caught  or  ignored. 

Once  a  signal  handler  is  installed,  it  remains  installed  until  another  ngvee  call  is  made,  or  an 
eseeve{2)  is  performed.  The  default  action  for  a  signal  may  be  reinstated  by  setting  tv_kand{er  to 
SIG_PFL;  this  default  is  termination  (with  a  core  image  for  starred  signab)  except  for  signals 
marked  with  •  or  t*  Signab  marked  with  •  are  dbcarded  if  the  action  b  SIG_PFL;  signals 
marked  with  t  cause  the  process  to  stop.  If  tv_hahdler  b  SIGJGN  the  signal  b  subsequently 
ignored,  and  pending  instances  of  the  signal  are  dbcarded. 

If  a  caught  signal  occurs  during  certmn  system  calls,  causing  the  call  to  terminate  prematurely, 
the  call  is  automatically  restarted.  In  particular  thb  can  occur  during  a  read  or  wrtte(2)  on  a  slow 
device  (such  as  a  terminal;  but  not  a  file)  and  during  a  tnatl(2). 

After  a  fork{2)  or  vf9rk{2)  the  child  inherits  all  signab,  the  signal  mask,  and  the  signal  stack. 

The  execve{2)  call  resets  all  caught  signab  to  default  action;  ignored  signab  remain  ignored;  the 
signal  mask  remains  the  same;  the  signal  stack  state  b  reset. 

Notes 

The  mask  specified  in  vee  b  not  allowed  to  block  SIGKILL,  SIGSTOP,  or  SIGCONT.  Thb  is 
done  silently  by  the  system. 

RETURN  VALUE 

A  0  value  indicated  that  the  call  succeeded.  A  -1  return  value  indicates  an  error  occured  and 
errne  is  set  to  indicated  the  reason. 


ERRORS 

Sigvee  will  fail  and  no  new  signal  handler  will  be  installed  if  one  of  the  following  occurs: 

(EFAULTj  Either  vec  or  ovee  points  to  memory  which  b  not  a  valid  part  of  the  process 
addri»8  space. 

|B|NVAL]  Sif  b  hot  a  valid  signal  number. 

(ElNyAL]  An  attempt  b  made  to  ignore  or  supply  a  handler  for  SIGKILL  or  SIGSTOP. 

(EINVAL)  An  attempt  b  made  to  ignore  SIGCONT  (by  default  SIGCONT  b  ignored). 

SEE  ALSO 

kill(l),  ptrace(^),  kill(2),  sigblock(2),  sig8etmask(2),  Blgpau5e(2)  8ig8tack(2),  8igvec(2),  setjmp(3), 
tty(4) 
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NOTES  (VAX-11) 

The  handler  routine  can  be  declared: 


handler(sig,  code,  scp) 
int  sig,  code; 
struct  sigcontext  *8cp; 

Here  »if  is  the  signal  number,  into  which  the  hardware  faults  and  traps  are  mapped  as  defined 
below.  Code  is  a  parameter  which  is  either  a  constant  as  given  below  or,  for  compatibility  mode 
faults,  the  code  provided  by  the  hardware  (Compatibility  mode  faults  are  distinguished  from  the 
other  SIGILL  traps  by  having  PSL_CM  set  in  the  psl).  Sep  is  a  pointer  to  the  eigeontext  struc¬ 
ture  (defined  in  <9ignal.h>),  used  to  restore  the  context  from  before  the  signal. 

The  following  defines  the  mapping  of  hardware  traps  to  signals  and  codes.  All  of  these  symbols 
are  defined  in  <9ignat.h>: 

Hardware  condition  Signal  Code 


Arithmetic  traps: 

Integer  overflow  SIGFPE  FPE_INTOVF_TRAP 

Integer  division  by  zero  SIGFPE  FPE_INTDIV_TRAP 

Floating  overflow  trap  SIGFPE  FPE_FLTOVF_TRAP 

Floating/decimal  division  by  lero  SIGFPE  FPEJ!’LTDIV_TRAP 


Floating  underflow  trap 
Decimal  overflow  trap 
Subscript-range 
Floating  overflow  fault 
Floating  divide  by  zero  fault 
Floating  underflow  fault 
Length  access  control 
Protection  violation 
Reserved  instruction 
Customer-reserved  instr. 
Reserved  operand 
Reserved  addressing 
Trace  pending 
Bpt  instruction 
Compatibility-mode 
Cbme 
Chms 
Chmu 

BUGS 

This  manual  page  is  confusing. 


SIGFPE  FPE_FLTUND_TRAP 

SIGFPE  FPEJ>ECOVF_TRAP 

SIGFPE  FPE_SUBRNG_TRAP 

SIGFPE  FPEJFLTOVF_FAULT 
SIGFPE  FPEJ’LTDIVJ'AULT 

SIGFPE  FPE_FLTUND_rAULT 
SIGSEGV 
SIGBUS 

SIGILL  ILLJIESADJFAULT 

SIGEMT 

SIGILL  ILL.PRIVINJFAULT 

SIGILL  ILLJlESOP_FAULT 

SIGTRAP 
SIGTRAP 

SIGILL  hardware  supplied  code 

SIGSEGV 

SIGSEGV 

SIGSEGV 
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NAME 

socket  -  create  an  endpoint  for  conuRunication 
SYNOPSIS 

^Include  <8y8/type8.h> 

#lnclude  <8y8/8oeket.h> 

8  as  BOcket(af,  type,  protocol) 

Int  8,  af,  type,  protocol; 

DESCRIPTION 

Socket  creates  an  endpoint  for  communication  and  returns  a  descriptor^ 


The  of  parameter  specifies  an  address  format  with  which  addresses  specified  in  later  operations 
using  the  socket  should  be  interpreted.  These  formats  are  defined  in  the  include  file 
<8ysl $oeket.h> .  The  currently  understood  formats  are 


AFJUNDC 

AFJNET 

AFJPUP 

AFJMPLINK 


(UNIX  path  names), 

(ARPA  Internet  addresses), 

(Xerox  FUP-I  Internet  addresses),  and 
(IMP  “host  at  INff“  addresses). 


The  socket  has  the  indicated  type  wh&h  specifies  the  semantics  of  communfcation.  Currently 
defined  types  arer 

SOCK.iSTREAM 

SOCK_DGRAM 

SOCK_RAW 

SOCK_SEQPACKET 

SOCKJIDM 


A  SOOK_STREAM  type  provides  sequenced,  reliable,  two-way  connection  based  byte  streams 
with  an  out-of-band  data  transmission  mechanism.  A  SOCK_PGRAM  socket  supports  datagrams 
(connectionless,  unreliable  messages  of  a  fixed  (typically  small)  maximum  length).  SOCK_RAW 
sockets  provide  access  to  internal  network  interfaces.  The  types  SOCKJRAW,  which  is  available 
only  to  the/super-uset,  and  SOCK_SEQPACKET  and  SOCK_RDM,  which  are  planned,  but  not 
yet  implemented,  are  not  described  here. 

The  protocol  Specifies  a  particular  protocol  to  be  used  with  the  socket.  Normally  only  a  single 
protocol  existi  to  support  a  particular  socket  type  using  a  given  address  format.  However,  it  is 
possible  that  many  protocols  may  exist  in  which  case  a  particular  protocol  must  be  specified  in 
this  manner.  The  protocol  number  to  use  is  particular  to  the  “communication  domain”  in  which 
communication  is  to  take  place;  see  «ertaee«(3N)  and  proteco/s(3N). 

Sockets  of  type  SOCK..STREAM  are  full-duplex  byte  streams,  similar  to  pipes.  A  stream  socket 
must  be  in  a  connected  state  before  any  data  may  be  sent  or  received  on  it.  A  connection  to 
another  socket  is  created  with  a  eonneet{2)  call.  Once  connected,  data  may  be  transferred  using 
reed(2)  and  write{2)  calb  or  some  variant  of  the  8end{2)  and  reev(2)  calls.  When  a  session  has 
been  completed  a  elo8e{2)  may  be  performed.  Out-of-band  data  may  also  be  transmitted  as 
described  in  8endl(2)  and  received  as  described  in  recu(2). 

The  communic^ibns  protocols  used  to  implement  a  SOCKJSTREAM  insure  that  data  is  not  lost 
or  duplicated.  If  h  piece  of  data  for  which  the  peer  protocol  has  buffer  space  cannot  be  success¬ 
fully  transmitted  within  a  reasonable  length  of  time,  then  the  connection  is  considered  broken  and 
calls  will  indicate  an  error  with  -1  returns  and  with  ETIMEDOUT  as  the  specific  code  in  the  glo¬ 
bal  variable  errno.  The  protocols  optionally  keep  sockets  “warm”  by  forcing  transmissions 
roughly  every  minute  in  the  absence  of  other  activity.  An  error  is  then  indicated  if  no  response 
can  be  elicited  on  an  otherwise  idle  connection  for  a  extended  period  (e.g.  5  minutes).  A  SIG- 
PIPE  signal  is  raised  if  a  process  sends  on  a  broken  stream;  this  causes  naive  processes,  which  do 
not  handle  the  signal,  to  exit. 
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SOCK_DGRAM  and  SOCKJRAW  sockets  allow  sending  of  datagrams  to  correspondents  named 
in  8end{2)  calls.  It  is  also  possible  to  receive  datagrams  at  such  a  socket  with  recv(2). 

An  fcnH{2)  call  can  be  used  to  specify  a  process  group  to  receive  a  SIGURG  signal  when  the  out- 
of-band  data  arrives. 

The  operation  of  sockets  is  controlled  by  socket  level  optienf.  These  options  are  defined  in  the 
file  <$]ief8ocket.h>  and  explained  below.  Setioekopt  and  gtiaockopt[^  are  used  to  set  and  get 
options,  respectively. 

SO_DEBUG  turn  on  recording  of  debugging  information 

SO_REUSEADDR  allow  local  address  reuse 

SO_KEEP ALIVE  keep  connections  alive 

SO_pONTROUTE  do  no  apply  routing  on  outgoing  messages 
SO.LINGER  linger  on  close  if  data  present 

SOJDONTLINGER  do  not  linger  on  close 

;  1 

SO.DEBUu  enables  debugging  in  the  underlying  protocol  modules.  SO^EUSEADDR  indicates 
the  rules  used  in  validating  addresses  supplied  in  a  bind{2)  call  should  allow  reuse  of  local 
addresses.  SO^KEEP ALIVE  enables  the  periodic  transmission  of  messages  on  a  connected  socket. 
Should  the  connected  party  fail  to  respond  to  these  messages,  the  connection  is  considered  broken 
and  processes  using  the  socket  are  notified  via  a  SIGPIPE  signal.  SOJ)ONTROUTE  indicates 
that  outgoing  messages  should  bypass  the  standard  routing  facilities.  Instead,  messages  are 
directed  to  the  appropriate  network  interface  according  to  the  network  portion  of  the  destination 
address.  SOJ^INGER  and  SOJDONTLINGER  control  the  actions  taken  when  unsent  message 
are  queued  on  socket  and  a  clo8e[2)  is  performed.  If  the  socket  promises  reliable  delivery  of  data 
and  SO JLINGER  is  set,  the  system  will  block  the  process  on  the  close  attempt  until  it  is  able  to 
transmit  the  data  or  until  it  decides  it  is  unable  to  deliver  the  information  (a  timeout  period, 
termed  the  linger  interval,  is  specified  in  the  sctsockopt  call  when  SO_LINGER  is  requested).  If 
SOJDONTLINGER  is  specified  and  a  close  is  issued,  the  system  will  process  the  close  in  a 
manner  which  allows  the  process  to  continue  as  quickly  as  possible. 

RETURN  VALUE 

A  -1  is  retained  if  an  error  occurs,  otherwise  the  return  vaihe  is  a  descriptor  referencing  the 
socket. 

ERRORS 

The  socket  call  fails  if: 


|EAFNOSUPPORTj  The  specified  address  family  is  not  supported  in  this  version  of  the  ^stem. 
(ESOCKTNOSUPPORT) 

The  specified  socket  type  is  not  supported  in  this  address  family. 

IEPROTONOSUPPORtI 

The  specified  protocol  is  not  supported. 

jEMFILE)  The  per-process  descriptor  table  is  full. 

[ENOBUFS]  No  buffer  space  is  available.  The  socket  cannot  be  created. 


SEE  ALSO 

accept(2),  bind(2),  conneci(2),  get80ckname(2),  get8ockopt(2),  ioctl(2),  Ii5ten(2),  recv(2),  8elect(2), 
send(2),  6butdown(2),  8ocketpair(2) 

‘‘A  4.2BSD  Interprocess  Communication  Primer**. 


BUGS 

The  use  of  keepalives  is  a  questionable  feature  for  this  layer. 
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NAME 

socketpair  -  create  a  pair  of  connected  sockets 
SYNOPSIS 

#!nelude  <By«/typeaJk> 

#!nelude  <aya/aoek«t.h> 

8oefcetpaIr(d»  type,  protocol,  sv) 
l]|t  d,  type,  protocol} 

Int  ev^S]} 

DESCRIPTION 

The  eocketpair  system  call  creates  an  unnamed  padr  of  connected  soeketain  the  specified  domain 
d,  of  the  specified  type  and  using  the  optionally  specified  protocol.  The  descriptors  used  in 
referencing  the  new  sockets  are  returned  in  et>(0]  and  ev(l].  The  two  sockets  are  indistinguishable^ 

DIAGNOSTICS 

A  0  is  returned  if  the  call  succeeds,  -1  if  it  fails^ 

ERRORS 

The  call  succeeds  unless:. 

[EMFILE]  Too  many  descriptors  are  in  use  by  this  process.. 

(EAFNOSUPPORT)  The  specified  address  family  is  not  supported  on  this  machine. 
(EPROTONOSUPPORT) 

The  specified  protocol  is  not  supported  on  thb  machine. 
(EOPNOSUPPORT]  The  specified  protocol  does  not  support  creation  of  socket  pairs. 

(EFAULT]  The  address  tv  does  not  specify  a  valid  part  of  the  process  address  space. 

SEE  ALSO 

read(2),  write(2),  pipe(2) 

BUGS 

Thu  call  is  currently  implemented  only  for  the  UNIX  domain. 
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NAME 

stat,  Istat,  fstat  -  get  file  status 
SYNOPSIS 

#lnclud6  <By«/type#.h> 

#hielude  <sys/atat.h> 

•tat(psth,  buf) 
char  *path; 
struct  stat  *buf) 

lstat(path«  buf) 
char  *path{ 
struct  stat  *buf| 

fstat(fdf  buf)  . 

Int  fd| 

struct  stat  *buf) 

DESCRIPTION 

Stat  obtains  information  about  the  file  path.  Read,  write  or  execute  permission  of  the  named  file 
is  not  required,  but  all  directories  listed  in  the  path  name  leading  to  the  file  must  be  reachable. 

Letat  is  like  gtat  except  in  the  case  where  the  named  file  is  a  lymbolie  link,  in  which  case  Istat 
returns  information  about  the  link,  while  stat  returns  information  about  the  file  the  link  refer¬ 
ences. 

Fstat  obtains  the  same  information  about  an  open  file  referenced  by  the  argument  descriptor,  such 
as  would  be  obtained  by  an  open  call. 

Buf  is  a  pointer  to  a  stat  structure  into  which  information  is  placed  concerning  the  file.  The  con¬ 
tents  of  the  structure  pointed  to  by  buf 

struct  stat 


dev_t 

»t_dcv; 

/•  device  inode  resides  on  */ 

ino_t 

etjno; 

/*  this  inode’s  number  •/ 

ujhort 

stjmode; 

/*  protection  */ 

short 

Bt^nlink; 

f*  number  or  bard  links  to  the  file  */ 

short 

8t_uid; 

/*  user-id  of  owner  */ 

short 

8t^id; 

/*  group-id  of  owner  */ 

dev_t 

st^rdev; 

/*  the  device  type,  for  inode  that  is  device  */ 

off_t 

stjsize; 

/*  total  size  of  file  •/ 

time^t 

st.atime; 

j*  file  last  access  time  */ 

int 

stjsparel; 

timejt 

/*  file  last  modify  time  */ 

int 

st_8pare2; 

time_t 

8t_ctime; 

/*  file  last  status  change  time  *( 

int 

8t_8parc3; 

long 

stjbiksize; 

1*  optimal  blocksize  for  file  system  i/o  ops  *f 

lon^ 

st^blocks; 

/*  actual  number  of  blocks  allocated  */ 

lon^ 

8t_5pare4(2]; 

}: 

st_atime  Time  when  file  data  was  last  read  or  modified.  Ch2uiged  by  the  following  system 
calls:  mknod{2),  utimes{2),  read{2),  write{2),  and  trmeate(2).  For  reasons  of 
efficiency,.  st_atime  is  not  set  when  a  directory  is  searched,  although  this  would  be 
more  logical. 

8t_mtime  Time  when  data  was  last  modified.  It  is  not  set  by  changes  of  owner,  group,  link 
count,  or  mode.  Changed  by  the  following  system  calls:  mJbnod(2),  ub'mes(2). 
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write{2). 

st.ctime  Time  when  file  status  was  last  changed.  It  is  set  both  both  by  writing  and  changing 
the  i-node.  Changed  by  the  following  system  calls:  ehmod{2)  chown{2),  h'Rl:(2), 
mknod{2),  un/mib(2),  utimes{2),  write{2),  truncate{2). 

The  status  information  word  has  bits: 


#deane  S_IFMT 

0170000 

/♦  type  of  file  */ 

#define  S_IPDIR 

0040000 

directory  ♦/ 

#define  SJPCHR 

0020000 

/*  character  special 

#define  S.IFBLK 

0060000 

j*  block  special  */ 

#define  S.IFREG 

0100000 

/♦  regular  ♦/ 

#define  S_IFLNK 

0120000 

/♦  symbolic  link  */ 

#define  S_IPSOCK 

0140000 

/*  socket  */ 

#define  SJSUID 

0004000 

f*  set  user  id  on  execution  */ 

#define  SJSGID 

0002000 

/♦  set  group  id  on  execution  ♦/ 

#define  SJSVTX 

0001000 

/•  save  swapped  text  even  after  use  •/ 

#define  SJREAD 

0000400 

/*  read  permission,  owner  */ 

#define  S_IWRITE 

0000200 

j*  write  permission,  owner  */ 

#deflne  SJEXEC 

0000100 

/•  execute/searcb  permission,  owner  */ 

The  mode  bits  0000070  and  0000007  encode  group  and  others  permissions  (see  ehmod{2)). 

When  fd  is  associated  with  a  pipe,  fttat  reports  an  ordinary  file  with  an  i-node  number,  restricted 
permissions,  and  a  not  necessarily  meaningful  length. 

RETURN  VALUE 

Upon  successful  completion  a  value  of  0  is  returned.  Otherwise,  a  value  of  -1  is  returned  and 
srrne  is  set  to  indicate  the  error. 

ERRORS 

Stat  and  Mat  win  fail  if  one  or  mwe  of  the  following  are  true: 

(ENOTDIR)  A  component  of  the  path  prefix  is  not  a  directory. 

[BPERX^  The  pathname  contains  a  character  with  the  high-order  bit  set. 

[ENOENT]  The  pathname  was  too  long. 

(ENOENT)  The  named  file  does  not  exist. 

(EACCES]  Search  permission  is  denied  for  a  component  of  the  path  prefix. 

[EPAULT]  B^fot  name  points  to  an  invalid  address. 

Fetat  will  fail  if  one  or  both  of  the  following  are  true; 

(EBADP]  Fildee  Is  not  a  valid  open  file  descriptor. 

(EPAULT)  Buf  points  to  an  invalid  address. 

(ELOOP)  Too  many  symbolic  links  were  encountered  in  translating  the  pathname. 
CAVEAT 

The  fields  in  the  stat  structure  currently  marked  etjsparel,  8t_»pare2,  and  et_«pareS  axe  present 
in  preparation  for  inode  time  stamps  expanding  to  64  bits.  This,  however,  can  break  certain  pro¬ 
grams  which  depend  on  the  time  stamps  being  contiguous  (in  calls  to  u(tme«(2)). 

SEE  ALSO 

chmod(2),  cnown(2),  utime8(2) 

BUGS 

Applying  fetat  to  a  socket  returns  a  zero'd  buffer. 
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SYSTEM  CALLS 


SWAP0N(2) 


NAME 

swapon  -  add  a  swap  device  for  interleaved  paging/swapping 

SYNOPSIS 

8wapon(apeeUl) 
char  '''■pectali 

DESCRIPTION 

Swapon  makes  the  block  device  special  available  to  the  system  for  allocation  for  paging  and  swa]^ 
ping.  The  names  of  potentially  available  devices  are  known  to  the  system  and  defined  at  i^stem 
configuration  time.  The  size  of  the  swap  area  on  spectof  is  calculated  at  the  time  the  device  is 
first  made  available  for  swapping. 

SEE  ALSO 

8^apon(8),  conflg(8) 

BUGS 

There  is  no  way  to  stop  swapping  on  a  disk  so  that  the  pack  may  be  dismounted. 

This  call  will  be  upgraded  in  future  versions  of  the  system. 
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o 


NAME 

symliiik  -  make  symbolic  link  to  a  file 
SYNOPSIS 

symUi2k(hamel|  nameS) 
char  ^namelf  *name2| 

DESCRIPTION 

A  symbolic  link  namtB  is  created  to  namei  {nameS  is  the  name  of  the  file  created^  name!  is  the 
siring  used  in  creating  the  symbolic  link).  Either  name  may  be  an  arbitrary  path  name;  the  files 
need  not  be  on  the  same  file  system. 

RETURN  VALUE 

Upon  successfnl  completion^  a  zero  value  is  returned.  If  an  error  occ urs>  the  error  code  is  stored 
in  errno  and  a  -1  value  is  returned. 

ERRORS 

The  symbolic  link  is  made  unless  on  or  more  of  the  following  are  true: 

[EPERMJ  Either  name!  or  name£  contains  a  character  with  the  b^h^rder  bit  set. 
{ENOENT]  One  of  the  pathnames  specified  was  too  tong. 

[ENOTDIR]  A  component  of  the  name2  prefix  is  not  a  directory. 

(EEXIST)  NameB  already  exists. 

(EACCES]  A  component  of  the  namtg  path  prefix  denies  search  permission. 

[ER0FS]  The  file  nameg  would  reside  on  a  read*onty  file  system. 

[EFAULT]  Namei  or  nameg  points  outside  the  process’s  allocated  address  space. 

[ELOOP]  Too  may  symbolic  links  were  encountered  in  translating  the  pathname. 

SEE  ALSO 

link(2),  Id(1)»  unlmk(2) 
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SYNC  (2) 


NAME 

sync  -  update  super-block 

SYNOPSIS 

syneO 

DESCRIPTION 

Sync  causes  all  informatioa  in  core  memory  that  should  be  on  disk  to  be  written  out.  This 
includes  modified  super  blocks,  modified  i-nodes,  and  delayed  block  I/O. 

Sync  should  be  used  by  programs  which  examine  a  file  system,  for  example  feck,  if,  etc.  Sync  is 
inandatoiy  before  a  boot. 

SEE  ALSP 

%nc(2),  sync(8),  cron(8) 

BUGS 

The  writing,  although  scheduled,  is  not  necessarily  complete  upon  return  from  eyne. 


o 
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NAME 

syseall  -  indirect  system  call 
SYNOPSIS 

syBeeJl(number,  arg, »,.) 

DESCRIPTION 

performs  the  system  call  whose  assembly  language  interface  has  the  specified  number,  and 
arguments  arg 

'I’he  register  dO  value  of  the  ^stem  calt  is  returaeds. 

DIAGNdSTICS 

^hen  the  C-bit-is  set,  9^9 eaU  returns  -1  and  sets  the  external  variable  erme(s«e  tnfro(2)). 

BUGS 

^ere  is  no  way  to  simulate  system  calls  such  as  pipe(2),  which  return  values  in  register  dl. 


o 
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SYSTEM  CALLS 


TRUNCATE(2) 


NAME 

truncatei  ftnincate  -  truncate  a  file  to  a  specified  length 
SYNOPSIS 

truiieate(path9  length) 
char  ’^pathi 
int  lengthi 

ftruncate(fd|  length) 
int  fdt  lengthy 

DESCRIPTION 

Truncait  causes  the  file  named  by  path  or  referenced  by  fd  to  be  truncated  to  at  most  hngth  bytes 
in  size.  If  the  file  previously  ivas  larger  than  this  size,  the  extra  data  is  lost.  With  JtruncaU,  the 
file  must  be  open  for  writing. 

RETURN  VALUES 

A  value  of  0  is  returned  if  the  call  succeeds.  If  the  call  fails  a  -1  is  returned,  and  the  global  vari¬ 
able  errno  specifies  the  error. 

ERRORS 

Truncait  succeeds  unless: 

[EPERM]  The  pathname  contains  a  character  with  the  high-order  bit  set. 

(ENOENTj  The  pathname  was  too  long. 

(EN0TD1R|  A  component  of  the  path  prefix  of  path  is  not  a  directory. 

[ENOENT]  The  named  file  does  not  exist. 

[EACCES]  A  component  of  the  path  prefix  denies  search  permission. 

[EISDIR]  The  named  file  is  a  directory. 

[EROFS]  The  named  file  resides  on  a  read-only  file  system. 

(ETXTBSYj  The  file  is  a  pure  procedure  (shared  text)  file  that  is  being  executed. 

(EFAULT|  Name  points  outside  the  process’s  allocated  address  space. 

Firuncait  succeeds  unless: 

(EBADFJ  The  fd  is  not  a  valid  descriptor. 

(EINVAL]  The  fd  references  a  socket,  not  a  file. 

SEE  ALSO 

open(2) 

BUGS 

Partial  blocks  discarded  as  the  result  of  truncation  are  not  zero  filled;  this  can  result  in  holes  in 
files  which  do  not  read  as  zero. 

These  calls  should  be  generalized  to  allow  ranges  of  bytes  in  a  file  to  be  discarded. 
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SYSTEM  CALLS 


UMASK(2) 


NAME 

umask  -  set  file  creation  mode  mask 
SYNOPSIS 

oumaak  »  ttniaBk(numa8k) 

Int  oumaskr  numask; 

DESCRIPTION 

Umatk  sets  the  process’s  file  mode  creation  mask  to  numosJt  and  returns  the  pievions  value  of  the 
mask.  The  low-order  9  bits  of  numaek  are  used  whenever  a  file- is  created,  clearing  corresponding 
b|ts  in  the  file  mode  (see  ekmod(2)).  This  clearing  allows  eaek.user  to  restrict  the  default  access 
t^  bis  files. 

The  value  is  initially  022  (write  access  ^or  owner  only).  The  mash  is  inherited  by  child  processes. 
RETURN  VALUE 

Tile- previous  value  of  the  file  mode  mask  b  returned  by  the  caV. 

SEE  ALSp 

chmod(2),  mknod(^,  open(2) 


Q 
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SYSTEM  CALLS 


UNLINK(2) 


NAME 

unlink  -  remove  directory  entry 

SYNOPSIS 

unllnk(path) 
char  *path; 

DESCRIPTION 

Unlink  removes  the  entry  for  the  file  path  from  its  directory.  If  this  entry  was  the  last  link  to  the 
file,  and  no  process  has  the  file  open,  then  all  resources  associated  with  the  file  are  reclaimed.  If, 
however,  the  file  was  open  in  any  process,  the  actual  resource  reclamation  is  delayed  until  it  is 
closed,  even  though  the  directory  entry  has  disappeared. 

RETURN  VALUE 

Upon  successful  completion,  a  value  of  0  is  returned.  Otherwise,  a  value  of  -1  is  returned  and 
errno  is  set  to  indicate  the  error. 

ERRORS 

The  unlink  succeeds  unless: 

(EPERM|  The  path  contains  a  character  with  the  high^rder  bit  set, 

[ENOENT]  The  path  name  is  too  long. 

[ENOTDIR]  A  component  of  the  path  prefix  is  not  a  directory. 

(ENOENT]  The  named  file  does  not  exist. 

(EACCES]  Search  permission  is  denied  for  a  component  of  the  path  prefix. 

[EACCES]  Write  permission  is  denied  on  the  directory  containing  the  link  to  be  removed. 

[EPERM]  The  named  file  is  a  directory  and  the  effective  user  ID  of  the  process  is  not  the 
super-user. 

[EBUSY]  The  entry  to  be  unlinked  is  the  mount  point  for  a  mounted  file  system. 

[EROFS]  The  named  file  resides  on  a  read-only  file  system. 

[EPAULT]  Path  points  outside  the  processes  allocated  address  space. 

(ELOOPj  Too  many  symbolic  links  were  encountered  in  translating  the  pathname. 

SEE  ALSO 

clo8e(2),  link(2),  rmdir(2) 
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SYSTEM  CALLS 


UTIMES(2) 


NAME 

Utimes  -  set  file  times 
SYNOPSIS 

#lnelad«  <Bys/typeiJh> 

utlmes(flle«  tvp) 
char 

struct  tlm«v«l  *tvp[2]; 

DESCRIPTION 

The  ulimet  call  uses  the  “accessed"  and  “updated"  times  in  that  order  from  the  tvp  vector  to  set 
the  corresponding  recorded  times  for  file. 

The  caller  must  be  the  owner  of  the  file  or  the  supcNuser.  The  “inode-changed"  time  of  the  file  is 
set  to  the  current  time. 

RETURN  VALUE 

Upon  successful  completion,  a  value  of  0  is  returned.  Otherwise,  a  value  of  -1  is  returned  and 
errito  is  set  to  indicate  the  error. 

ERRORS 

Utime  will  fail  if  one  or  more  of  the  following  are  true: 

(EPERh^  The  pathname  contained  a  character  with  the  high-order  bit  set. 

(ENOENTf  The  pathname  was  too  long. 

(ENOBNT]  The  named  file  does  not  exnt. 

(ENOTDIR}  A  component  of  the  path  prefix  is  not  a  directory. 

{EACCES^  A  component  of  the  path  prefix  denies  search  permission. 

(EPERh^  The  process  is  not  super-user  and  not  the  owner  of  the  file. 

[E^CCES]  The  effective  user  ID  is  not  super-user  and  not  the  owner  of  the  file  and  time$  is 
NULL  and  write  access  is  denied. 

|EROFS}  The  file  system  containing  the  file  is  mounted  read-only. 

(EFAULT]  Tvp  points  outside  the  process's  allocated  address  space. 

(ELOOP}  Too  many  symbolic  links  were  encountered  in  translating  the  pathname. 

SEE  ALSO 

stat(2) 
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SYSTEM  CALLS 


VADVISE(2) 


NAME 

vadvise  -  give  advice  to  paging  system 
SYNOPSIS 

#inelude  <sys/vadvlBe.h> 

vadvtfe(param) 

Int  paramf 

DESCRIPTION 

Vadvite  is  used  to  inform  the  system  that  process  paging  behavior  merits  special  consideration. 
Parameters  to  vadvite  are  defined  in  the  file  <vadvb«Ji>.  Currently,  two  calls  t  vadviae  are 
implemented. 

The  call 

viu}vlse(VA_ANOM)t 

advises  that  the  paging  behavior  is  not  likely  to  be  well  bandied  by  the  system’s  default  algo- 
rithm,  since  reference  information  is  collected  over  macroscopic  intervals  (e.g.  10-20  seconds)  will 
not  serve  to  indicate  future  page  references.  The  system  in  this  case  will  choose  to  replace  pages 
with  little  emphasis  placed  on  recent  usage,  and  more  emphasis  on  referenceless  circular  behavior. 
It  is  eaaential  that  processes  which  have  very  random  paging  behavior  (such  as  LISP  during  gar¬ 
bage  collection  of  very  large  address  spaces)  call  vadviae,  as  otherwise  the  system  has  great 
difficultjf  dealing  with  their  page-consumptive  demands. 

The  call 


vndvlse(VA_NORM)| 

restores  default  paging  replacement  behavior  after  a  call  to 
vadvlse(VA_ANOM)} 

BUGS 

Will  go  away  soon,  being  replaced  by  a  per-page  madviae  facility. 
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VFORK(2) 


NAME 

vfork  -  spawn  new  process  in  a  virtual  memory  efficient  way 

SYNOPSIS 

pid  s  vforkO 
tnt  pld} 

DESCRIPTION 

Vfork  can  be  used  to  create  new  processes  without  fully  copying  the  address  space  of  the  old  pro¬ 
cess,  which  is  horrendously  inefficient  in  a  paged  environment.  It  is  useful  when  the  purpose  of 
fork{2)  would  have  been  to  create  a  new  ^rstem  context  for  an  execve.  Vfork  differs  from  fork  in 
that  the  child  borrows  the  parent’s  memory  and  thread  of  control  until  a  call  to  exeeve{2)  or  an 
exit  (either  by  a  call  to  exit{2)  or  abnormally.)  The  parent  process  is  suspended  while  the  child  is 
using  its  resources. 

Vfork  returns  0  in  the  child’s  context  and  (later)  the  pid  of  the  child  in  the  parent’s  context. 

Vfork  can  normally  be  used  just  like  fork.  It  does  not  work,  however,  to  return  while  running  in 
the  childs  context  from  the  procedure  which  called  vfork  since  the  eventual  return  from  vfork 
would  then  return  to  a  no  longer  existent  stack  frame.  Be  careful,  also,  to  call  rather  than 
exit  if  you  can’t  exeeve,  since  exit  will  flush  and  close  standard  I/O  channels,  and  thereby  mess  up 
the  parent  processes  standard  I/O  data  structures.  (Even  with  fork  it  is  wrong  to  call  exit  since 
buffered  data  would  then  be  flushed  twice.) 

SEE  ALSO 

fork(2),  execve(2),  sigvee(2),  wait(2), 

DIAGNOSTICS 

Same  as  for  fork. 

BUGS 

This  system  call  will  be  eliminated  when  proper  system  sharing  mechanisms  are  implemented. 
Users  should  not  depend  on  the  memory  sharing  semantics  of  vfork  as  it  will,  in  that  case,  be 
made  synonymous  to  fork. 

To  avoid  a  possible  deadlock  situation,  processes  which  are  children  in  the  middle  of  a  vfork  are 
never  sent  SIGTTOU  or  SIGTTIN  signals;  rather,  output  or  ioeth  are  allowed  and  input  attempts 
result  in  an  end-of-flle  indication. 
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VHANGUP(2) 


NAME 

vhangup  -  virtually  “hangup”  the  current  control  terminal 

SYNOPSIS 

vhangupO 

DESCRIPTION 

Vhangup  is  used  by  the  initialization  process  tnti(8)  (among  others)  to  arrange  that  users  are  given 
“clean”’  terminals  at  login,  by  revoking  access  of  the  previous  users’  processes  to  the  terminal. 
To  effect  this,  vhangup  searches  the  system  tables  for  references  to  the  control  terminal  of  the 
invoking  process,  revoking  access  permissions  on  each  instance  of  the  terminal  which  it  finds. 
Further  attempts  to  access  the  terminal  by  the  affected  processes  will  yield  i/o  errors  (EBADF). 
Finally,  a  hangup  signal  (SIGHUP)  is  sent  to  the  process  group  of  the  control  terminal. 

SEE  ALfiO 

init  (8) 

BUGS 

Access  to  the  control  terminal  via  /dev/tty  is  still  possible. 

This  call  should  be  replaced  by  an  automatic  mechanism  which  takes  place  on  process  exit. 
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SYSTEM  CALLS 


WAIT(2) 


NAME 

wait,  waits  -  wait  for  process  to  terminate  or  stop 
SYNOPSIS 

#include  <0ys/walt.h> 

pid  Bs  walt(atatua) 

Int  ptd) 

union  wait  ^status; 

p!d  a  walt(O) 

Int  pld| 

#lnelude  <tyB/tlme.h> 

#lnelud«  <ay>/rwouree.h> 

pld  bb  walt3(atatust  optional  ruaago) 

Int  pld| 

union  wait  *atatua; 

Int  optional 

struct  rusage  *ru8age| 

DESCRIPTION 

Wait  causes  its  caller  to  delay  until  a  signal  is  received  or  one  of  its  child  processes  terminates  or 
stops  due  to  tracing.  If  any  child  has  died  or  stopped  due  to  tracing  ajid  this  has  not  been 
reported  via  wait,  return  u  immediate,  returning  the  process  id  and  exit  status  of  one  of  those 
children.  If  that  child  had  died,  it  is  discarded.  If  there  are  no  children,  return  is  immediate  with 
the  value  -1  returned.  If  there  are  only  running  or  stopped  but  reported  children,  the  calling 
processes  is  suspended. 

On  return  from  a  successful  wait  call,  etatuf  is  nonzero,  and  the  high  byte  of  status  contains  the 
low  byte  of  the  argument  to  exit  supplied  by  the  child  process;  the  low  byte  of  status  contains  the 
termination  status  of  the  process.  A  more  precise  definition  of  the  status  word  is  given  in 
<sys(wait.h>. 

Waits  is  an  alternate  interface  which  allows  both  non>blocking  status  collection  and  the  status  of 
children  stopped  by  any  means.  The  status  parameter  u  defined  as  above.  The  options  parame¬ 
ter  is  used  to  indicate  the  call  should  not  block  if  there  are  no  processes  which  have  status  to 
report  (WNOHANQ),  and/or  that  children  of  the  current  process  which  are  stopped  due  to  a 
SIQTTIN,  SIGTTOU,  SIOTSTP,  or  SIQSTOP  signal  are  eligible  to  have  their  status  reported  as 
well  (WUNTRACED).  A  terminated  child  is  discarded  after  it  reports  status,  and  a  stopped  pro¬ 
cess  will  not  report  its  status  more  than  once.  If  rusage  is  non-zero,  a  summary  of  the  resources 
used  by  the  terminated  process  and  all  its  children  is  returned.  (This  information  is  currently  not 
available  for  stopped  processes.) 

When  the  WNOHANG  option  is  specified  and  no  processes  have  status  to  report,  waits  returns  a 
pid  of  0.  The  WNOHANG  ana  WUNTRACED  options  may  be  combined  by  sr’ing  the  two 
values. 

NOT^ii 

See  9igvte{^)  for  a  list  of  termination  statuses  (signals);  0  status  indicates  normal  termination.  A 
special  status  (0177)  is  returned  for  a  stopped  process  which  has  not  terminated  and  can  be  res¬ 
tarted;  see  ptrace{2)  and  8igvcc(2Y  If  the  0200  bit  of  the  termination  status  is  set,  a  core  image  of 
the  process  was  produced  by  the  system. 

If  the  parent  process  terminates  witkout  waiting  on  its  children,  the  initialization  process  (process 
ID  a  1)  inherits  the  children. 

Wait  and  waits  are  automatically  restarted  when  a  process  receives  a  signal  while  awaiting  termi¬ 
nation  of  a  child  process. 
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SYSTEM  CALLS 


WAIT(2) 


RETURN  VALUE 

If  wait  leturns  due  to  a  stopped  due  to  tracing  or  terminated  child  process,  the  process  ID  of  the 
child  is  returned  to  the  calling  process.  Otherwise,  a  value  of  —1  is  returned  and  trrno  is  set  to 
indicate  the  error. 

Waits  returns  -1  if  there  are  no  children  not  previously  waited  for;  0  is  returned  if  WNOHANG 
is  specified  and  there  are  no  stopped  or  exited  children. 


ERRORS 

Wait  will  fail  and  return  immediately  if  one  or  more  of  the  following  are  true: 


(ECHILD) 

jeFAULT) 

SEE  ALSO 

exit(2) 


The  calling  process  has  no  existing  unwaited'for  child  processes. 
The  0tatu$  or  rusage  arguments  point  to  an  illegal  address. 
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NAME 

write,  wrltev  -  write  on  a  file 

SYNOPSIS 

wrlte(<lt  buf,  nbytee) 

Int  d) 
char  *buf^ 

Int  nbytei) 

#lne!ude  <ay8/typee.h> 

#lneiude  <eys/ulo.h> 

wrltev(df  loVf  loveelen) 

Int  df 

■truet  lovee  *lov} 

Int  loveeleni 

DESCRIPTION 

Write  attempts  to  write  nbytee  of  data  to  the  object  referenced  by  the  descriptor  d  from  the  buffer 
pointed  to  by  byf.  Writev  performs  the  same  action,  but  gathers  the  output  data  from  the  iovien 
buffers  specified  by  the  members  of  the  iov  array:  iovjO],  iov(l],  etc. 

On  objects  capable  of  seeking,  the  write  starts  at  a  position  given  by  the  pointer  associated  with 
d,  see  /sesil;(2).  Upon  return  from  write,  the  pointer  is  incremented  by  the  number  of  bytes  actu¬ 
ally  written. 

Objects  that  are  not  capable  of  seeking  alws^s  write  from  the  current  position.  The  value  of  the 
pointer  associated  with  such  an  object  is  undefined. 

If  the  real  user  is  not  the  super-user,  then  write  clears  the  set-user-id  bit  on  a  file.  This  prevents 
penetration  of  system  security  by  a  user  who  “captures’*  a  writable  set-user-id  file  owned  by  the 
super-user. 

RETURN  VALUE 

Upon  successful  completion  the  number  of  bytes  actually  writen  is  returned.  Otherwise  a  -1  is 
returned  and  errno  is  set  to  indicate  the  error. 

ERRORS 

Write  will  fail  and  the  file  pointer  will  remain  unchanged  if  one  or  more  of  the  following  are  true: 
[EBADFj 
(EPIPE) 

lEPIPE) 

(EFBIG) 

(EFAULTj 

SEE  ALSO 

l8eek(2),  open(2),  pipe(2) 


D  is  not  a  valid  descriptcv  open  for  writing. 

An  attempt  is  made  to  write  to  a  pipe  that  is  not  open  for  reading  by  any  pro- 
cesB.^ 

An  attempt  is  made  to  write  to  a  socket  of  type  SOCK_STREAM  which  is  not 
connected  to  a  peer  socket. 

An  attempt  was  made  to  write  a  file  that  exceeds  the  process’s  file  size  limit  or 
the  maximum  me  size. 

Part  o(\  t’ov  or  daia  to  be  written  to  the  file  points  outside  the  process’s  allocated 
address  space. 
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NAME 

intro  -  introdnction  to  library  functions 


DESCRIPTION 

Section  3  describes  functions  found  in  libraries. 

This  section  describes  subroutines  found  in  the  system  libraries. 

The  main  C  library  is  /lib/Bbc.a,  and  contains  all  the  system  call  entry  points  described  in  sec¬ 
tion  2  as  well  as  functions  described  in  several  subsections  here.  The  primary  functions  in  the  C 
library  are  described  in  the  main  section  3.  Functions  associated  with  the  "standard  I/O  library” 
used  by  many  C  programs  are  found  in  section  3S.  The  libc  library  also  includes  the  Internet  net¬ 
work  functions  described  in  section  3N  and  routines  providing  compatibility  with  other  UNIX  sys¬ 
tems  as  described  in  section  3C  as  well  as  all  the  system  entry  points  from  section  2. 


Other  sections  here  are: 

(3F)  The  3F  functions  are  all  functicms  callable  from  FORTRAN.  These  functions  perform 
the  same  jobs  as  the  straight  "3”  functions  do  for  C  programmers.  There  are  in  fact 
three  FORTRAN  libraries,  namely  -1U77  which  contains  the  system  interface  routines, 
-1177  which  is  the  I/O  interface  library,  and  -1F77  which  is  everything  not  contained  in 
the  other  two.  These  libraries  are  searched  automatically  by  the  loader  when  loading 
FORTRAN  programs. 

(3M)  These  functions  constitute  the  math  library.  C  declarations  for  the  types  of  functions 
may  be  obtained  from  the  include  file  <matk.h>.  To  use  these  functions  with  C  pro¬ 
grams  use  a  -Im  option  with  ec(l).  They  are  automatically  loaded  as  needed  by  the  For¬ 
tran  and  Pascal  compilers  /77(1)  and  pc(l). 

(3X)  Various  specialized  libraries  have  not  been  given  distinctive  captions.  Files  in  which  such 
libraries  are  found  are  named  on  appropriate  pages  if  they  don’t  appear  in  the  Hbc  library. 


FILES 


/lib/libc.a 

/usr/lib/Iibcjp.a 

/usr/lib/libm.a 

/usr/lib/libm_p.a 

/u8r/lib/libU77.a 

/u8r/Ub/libI77.a 

/u8r/Ub/llbF77.a 

/U8r/lib/libcur8e8.a 

/uBr/lib/libdbm.a 

/u8r/lib/libmp.a 

/usr/iib/libtermcap.a 

/usr/lib/libtermcapji.a 

/usr/lib/libtermlib 

/u8r/lib/libtermlibj>.a 

/usr/lib/libplot.a 

/usr/lib/lib300.a 

/u8r/Iib/lib3008.a 

/uBr/Iib/lib4014.a 

/u8r/lib/iib450.a 

SEE  ALSO 


C  Library  ((2),  (3),  (3N)  and  (30)  routines) 
Profiling  C  library  (for  gproJ{l)) 

Math  Library  -Im  (see  section  3M) 

Profiling  version  of  -Im 

FORTRAN  system  interface  (see  section  3F) 

FORTRAN  I/O  (see  section  3F) 

FORTRAN  everything  else  (see  section  3F) 
screen  management  routines  (see  curses(3X) 
data  base  management  routines  (see  d6m(3X)) 
multiple  precision  math  library  (see  mp(3X)) 
terminal  handling  routines  (see  fermcap(3X)) 


plot  routines  (see  p/of(3X)) 


n 

ft 


intro(3C),  intro(3S),  intro(3F),  intro(3M),  intro(3N),  nm(l),  ld(l),  cc(l),  f77(l),  intro(2) 


DIAGNOSTICS 

Functions  in  the  math  library  (section  3M)  may  return  conventional  values  when  the  function  is 
undefined  for  the  given  arguments  or  when  the  value  is  not  representable.  In  these  cases  the 
external  variable  trrno  (see  m^r^(2))  is  set  to  the  value  EDOM  (domain  error)  or  ERANGE  (range 
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error).  The  values  of  EDOM  and  ERANGB  are  defined  in  the  include  file  <errno.h>. 
LIST  OF  FUNCTIONS 


Namt 

Appears  on  Page 

Description 

abort 

abort. 3 

generate  a  fault 

abs 

abs.S 

integer  absolute  value 

alarm 

alarm.Sc 

schedule  signal  after  specified  time 

alloca 

malloc.3 

memory  allocator 

aipbasort 

scandir.S 

scan  a  directory 

asctime 

ctime.3 

convert  date  and  time  to  ASCII 

assert 

assert.  3 

program  verification 

atof 

atof.3 

convert  ASCII  to  numbers 

atoi 

atof.3 

convert  ASCII  to  numbers 

atol 

atof.3 

convert  ASCII  to  numbers 

bemp 

b8tring.3 

bit  and  byte  string  operations 

bcopy 

b8tring.3 

bit  and  byte  string  operations 

bzero 

b8tring.3 

bit  and  byte  string  operations 

calloc 

maUoc.3 

memory  allocator 

cfree 

malloc.3 

memory  allocator 

clearerr 

ferror.Ss 

stream  status  inquiries 

closedir 

directory  .3 

directory  operations 

closelog 

syslog.S 

control  system  log 

crypt 

crypt.3 

DES  encryption 

ctime 

ctime.3 

convert  date  and  time  to  ASCII 

dysize 

ctime.3 

convert  date  and  time  to  ASCII 

ecvt 

ecvt. 3 

output  conversion 

edata 

end.3 

last  locations  in  program 

encrypt 

crypt.3 

DES  encryption 

end 

end.3 

last  locations  in  program 

endfsent 

getfsent.S 

get  file  system  descriptor  file  entry 

endgrent 

getgrent.3 

get  group  file  entry 

endhostent 

gethostent.Sn 

get  network  host  entry 

endnetent 

getnetent.Sn 

get  network  entry 

endprotoent 

getprotoent.3n 

get  protocol  entry 

endpwent 

getpwent.3 

get  password  file  entry 

endservent 

getservent.dn 

get  service  entry 

environ 

execl,3 

execute  a  file 

errno 

perror.3 

system  error  messages 

etext 

end.3 

last  locations  in  program 

execl 

execl.3 

execute  a  file 

execle 

execl.3 

execute  a  file 

execlp 

execl.3 

execute  a  file 

execv 

execl.S 

execute  a  file 

execvp 

execl.3 

execute  a  file 

exit 

exit.3 

terminate  a  process  after  Bushing  an; 

fclose 

fclose.  3s 

close  or  flush  a  stream 

fcvt 

ccvt.3 

output  conversion 

fdopen 

f open. 3s 

open  a  stream 

feof 

ferror.Ss 

stream  status  inquiries 

f error 

ferror.Ss 

stream  status  inquiries 

fflush 

fclose.Ss 

close  or  flush  a  stream 

fits 

bstring.S 

bit  and  byte  string  operations 

fgetc 

getc.Ss 

get  character  or  integer  from  stream 

fgets 

gets. 3s 

get  a  string  from  a  stream 
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flleno 

fopen 

fprintf 

fputc 

fputs 

fread 

free 

freopen 

frexp 

fscanf 

fseek 

ftell 

ftime 

fwrite 

gcvt 

getc 

getcbar 

gctenv 

getfsent 

getfeflie 

getfsspec 

getfstype 

getgrent 

getgrgid 

getgmam 

getbostbyaddr 

getbostbyname 

getboetent 

getlogio 

getnetbyaddr 

getnetbyname 

getneteot 

getopt 

getpass 

getprotobyname 

getprotobynumber 

getprotoent 

getpw 

getpwent 

getpwnam 

getpwuid 

gets 

getservbyname 

getservbyport 

getservent 

getw 

getwd 

gnitime 

gWy 

htont 

btons 

index 

inetjaddr 


ferror.Ss 

fopen.Ss 

printf.Ss 

putc.Ss 

puts.Ss 

fread.Ss 

malloc.3 

fopen.38 

frexp.3 

ecanf.Sa 

feeek.3a 

f6eek.3s 

time.Sc 

fread.3s 

ecvt.3 

getc.3s 

getc.38 

getenv.3 

getf8ent.3 

getf8ent.3 

getfsent.3 

getfsent.S 

getgrent.3 

getgrent.3 

getgrent.3 

getho8tent.3n 

getbo8tent.3n 

getbo8tent.3n 

getlogin.d 

getneteBt.3n 

getnetent.3tt 

getnetent.3n 

getopt.3c 

getpa88.3 

getprotoent.Sn 

getprotoent.3n 

getprotoent.Sn 

getpw.3 

getpwent.3 

getpwent.3 

getpwent.3 

gets.3B 

get8ervent.3n 

get8ervent.3n 

geteervent.3n 

getc  .3s 

getwd.3 

ctime.3 

8tty.3c 

byteorder.3o 

byteorder.3n 

etring.S 

inet.3n 


stream  status  inquiries 
open  a  stream 

formatted  output  conversion 
put  character  or  word  on  a  stream 
put  a  string  on  a  stream 
buffered  binary  input/ontput 
memory  allocator 
open  a  stream 

split  into  mantissa  and  exponent 
formatted  input  conversion 
reposition  a  stream 
reposition  a  stream 
get  date  and  time 
buffered  binary  input/output 
output  conversion 

get  character  or  integer  from  stream 

get  character  or  integer  from  stream 

value  for  environment  name 

get  file  system  descriptor  file  entry 

get  file  system  descriptor  file  entry 

get  file  system  descriptor  file  entry 

get  file  system  descriptor  file  entry 

get  group  file  entry 

get  group  file  entry 

get  group  file  entry 

get  network  host  entry 

get  network  host  entry 

get  network  host  entry 

get  login  name 

get  network  entry 

get  network  entry 

get  network  entry 

get  option  letter  from  argv 

read  a  password 

get  protocol  entry 

get  protocol  entry 

get  protocol  entry 

get  name  from  uid 

get  password  file  entry 

get  password  file  entry 

get  password  file  entry 

get  a  string  from  a  stream 

get  service  entry 

get  service  entry 

get  service  entry 

get  character  or  integer  from  stream 
get  current  working  directory  pathname 
convert  date  and  time  to  ASCII 
set  and  get  terminal  state 

convert  values  between  host  and  network  byte  order 
convert  values  between  host  and  network  byte  order 
string  operations 
Internet  address  manipulation 
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inetjnaof 

inet.Sn 

Internet  address  manipulation 

inet^makeaddr 

inet.Sn 

Internet  address  manipulation 

inct.netof 

inet.Sn 

Internet  address  manipulation 

inet^nctwork 

inet.Sn 

Internet  address  manipulation 

inet^ntoa 

inet.Sn 

Internet  address  manipulation 

initgroups 

initgroup8.3 

initialize  group  access  list 

initstate 

random.3 

better  random  number  generator;  routines  for  changing  generators 

insqu« 

insque-S 

insert/remove  element  from  a  queue 

isalnum 

ctype.3 

character  classification  macros 

isalpha 

ctype.3 

character  classification  macros 

isascii 

ctype.3 

character  classification  macros 

isatty 

ttyname.3 

find  name  of  a  terminal 

iscntrl 

ctype.3 

character  classification  macros 

isdigit 

ctype.3 

character  classification  macros 

isgraph 

ctype.3 

character  classification  macros 

isinf 

isinf  .3 

test  for  indeterminate  floating  point  values 

islower 

ctype.3 

character  classification  macros 

isnan 

isinf.S 

test  for  indeterminate  floating  point  values 

isprint 

ctypc.3 

character  classification  macros 

ispunct 

ctype.3 

character  classification  macros 

isspace 

ctype.3 

character  classification  macros 

isupper 

ctype.3 

character  classification  macros 

Idexp 

frexp.3 

split  into  mantissa  and  exponent 

localtime 

ctime.3 

convert  date  and  time  to  ASCII 

longjmp 

setjmp.S 

non-local  goto 

malloc 

malloc. 3 

memory  allocator 

mktemp 

mktemp.3 

make  a  unique  file  name 

modf 

frexp.3 

split  into  mantissa  and  exponent 

moncontrol 

monitor.3 

prepare  execution  profile 

monitor 

monitor.3 

prepare  execution  profile 

monstartup 

monitor.3 

prepare  execution  profile 

nice 

nice.Sc 

set  program  priority 

nlist 

nlist.3 

get  entries  from  name  list 

ntohl 

bytcorder.3n 

convert  values  between  host  and  network  byte  order 

ntohs 

byteorder.Sn 

convert  values  between  host  and  network  byte  order 

opendir 

directory  .3 

directory  operations 

openlog 

syslog.S 

control  system  log 

optarg 

getopt.Sc 

get  option  letter  from  argv 

optind 

getopt.Sc 

get  option  letter  from  argv 

pause 

pause.Sc 

stop  unto  signal 

pclose 

popen. 38 

initiate  I/O  to/from  a  process 

pcrror 

perror.3 

system  error  messages 

popen 

popen.  3s 

initiate  I/O  to/from  a  process 

printf 

printf.Ss 

formatted  output  conversion 

psignal 

psignal.3 

system  signal  messages 

putc 

putc  .38 

put  character  or  word  on  a  stream 

putchar 

putc.Ss 

put  character  or  word  on  a  stream 

puts 

puts.Ss 

put  a  string  on  a  stream 

putw 

putc.Ss 

put  character  or  word  on  a  stream 

qsori 

qsort.3 

quicker  sort 

rand 

rand. 3c 

random  number  generator 

random 

random.3 

better  random  number  generator;  routines  for  changing  generators 

rcmd 

rcmd.Sn 

routines  for  returning  a  stream  to  a  remote  command 
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rejcomp 

regex.3 

regular  expression  handler 

rcjexec 

regex.3 

regular  expression  handler 

readdir 

directory's 

directory  operations 

realloc 

malloc.S 

memory  allocator 

remqae 

inaque.S 

inaert/remove  element  from  a  queue 

rewind 

fseek.Sa 

reposition  a  stream 

rewinddir 

directory  .3 

directory  operations 

rexec 

rexec.Sn 

return  stream  to  a  remote  command 

rindex 

string.S 

string  operations 

rresvport 

rcmd.Sn 

routines  for  returning  a  stream  to  a  remote  command 

nteerok 

rcmd.Sn 

Eoutmea  (or  returning  a  stream  to  a  remote  command 

scandir 

acandirS 

scan  a  durectoiy 

ficanf 

acanf.3a 

fonnatted  input  conversion 

seekdir 

dfrectory.3 

directory  operations 

setbuf 

aetbuf-Ss 

assign  buffering  to  a  stream 

BetbuSer 

8etbitf.3s 

assign  buffering  to  a  stream 

setegid 

aetaid.S 

set  user  and  group  ID 

setenid 

aetttfd.3 

set  user  and  group  DT 

setfsent 

getfsent^S 

get  filesystem  descriptor  file  ent^ 

setgid 

aetuxd.3 

set  user  and  group  ID 

setgrent 

getgrent.3 

get  group  file  entry 

BethosCent 

gethoatent.Sn 

get  network  host  entry 

setjmp 

setjmp.3 

non*locatgoto 

aetkey 

crypt.3 

DES  encryption 

setlinebuf 

aetbuf.Sa 

assign  buffering  to  a  stream 

setnetent 

getnetent.Sn 

get  network  entry 

setprotoent 

getprotoent.Sn 

get  protocol  entry 

Betpwent 

getpwent.3 

get  password  file  entry 

setrgid 

aetuid.3 

set  user  and  group  ID 

aetruid 

aetuid.S 

set  user  and  group  ID 

setflervent 

getaervent.Sn 

get  service  entry 

aetstate 

randoin«3 

better  random  number  generator;  routines  for  changing  generators 

aetuid 

aetuid.S 

set  user  and  group  ID 

aignal 

signal.S 

simplified  software  signal  facilities 

Bleep 

aleep.S 

suspend  execution  for  interval 

aprintf 

printf.Sa 

formatted  output  conversion 

arand 

rand  .3c 

random  number  generator 

arandom 

random.S 

better  random  number  generator;  routines  for  changing  generators 

Bscanf 

acanf.Ss 

formatted  input  conversion 

atdio 

intro.Ss 

standard  buffered  input/output  package 

atrcat 

atring.3 

string  operations 

Btrcmp 

atring.S 

string  operations 

atrcpy 

atring.3 

string  operations 

atrlen 

atring.S 

string  operations 

atrncat 

atring.S 

string  operations 

atrncmp 

atring.S 

string  operations 

atrncpy 

atring.S 

string  operations 

atty 

atty.Sq 

set  and  get  terminal  state 

swab 

swab.S 

sw^  bytes 

sys^errlist 

perror.3 

system  error  messages 

ayajerr 

perror.3 

system  error  messages 

psignal.S 

system  signal  messages 

ayalog 

syslog.3 

control  ^stem  log 
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system 

system.S 

issue  a  shell  command 

o 

telldir 

directory  .3 

directory  operations 

time 

time.Sc 

get  date  and  time 

times 

times.Sc 

get  process  times 

timezone 

ctime.3 

convert  date  and  time  to  ASCII 

tmpnam 

tmpnam.Sc 

create  a  name  for  a  temporary  file 

ttyname 

ttyname.3 

find  name  of  a  terminal 

ttyslot 

ttyname.3 

find  name  of  a  terminal 

uUmit 

ulimit.Sc 

get  and  set  user  limits 

ungetc 

ungetc.Ss 

push  character  back  into  input  stream 

■ 

utime 

utime.Sc 

set  file  times 

valloc 

valloc.3 

aligned  memory  allocator 

varargs 

varargs.S 

variable  argument  list  ^ 

vlimit 

v]imit.3c 

control  maximum  system  resource  consumption 

vtimes 

vtimes.Sc 

get  information  about  resource  utilization 

I 
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NAME^ 

abort  -  generate  a  fault 
DESCRIPTION 

Abcrt  executes  an  instruction  Urbicb  is  illegal  in  user  mode.  This  causes  a  signal  that  normally 
terminates  the  process  with  a  core  dump,  which  may  be  useif  for  debugging. 

SEE  ALSO 

s(lb(lS),  signal(3),  «cil(2) 

DEiQNOSTICS 

Usual^  ‘IDT*  ttap  -  core  dumped*^  from  the  shell. 

BUGS 

t^e  ofruit  l^utbo-doe*  net  fiush:  standard  I/O  buffers.  Use  as  deseribedjn  £elo»e{SS)i 
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NAME 

abs  -  integer  absolute  value 

SYNOPSIS 

ab.(l) 

Int  1} 

DESCRIPTION 

Abs  returns  the  absolute  value  of  its  integer  operand. 

SEE  ALSO 

Soor(3M)  for  fabt 

BUGS 

Applying  the  abe  function  to  the  most  negative  integer  generates  a  result  which  is  the  most  nega> 
tive  integer.  That  is,  abs(0x80000000)  returns  0x80000000  as  a  result. 
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NAME 

asBert  -  program  verification 

SYNOPSIS 

#lnelttde 

SMert(exprenlon) 

DESCRIPTION 

Anert  is  a  macro  that  indicates  aepreteiott  is  expected  to  be  true  at  this  point  in  the  program^  It 
causes  an  ent{2)  with  a  diagnostic  comment  on  the  standard  outpnt  when  ezpreftien  h  false  (0). 
Compiling  with  the  ec(l)  option  -DNDEBUQ  effectively  deletes  assert  from  the  program. 

DIAGNOSTICS 

'Assertion  failed:  file  /  line  n. '  F  is  the  source  file  smd  n  the  sonrce  fine  number  of  the  tutert  state¬ 
ment. 
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NAME 

atof,  atoi,  atol  -  convert  ASCII  to  numbers 

SYNOPSIS 

double  atof(nptr) 
char  *nptr{ 

atol(nptr) 
char  *nptr| 

long  atol(nptr) 
char  *nptr{ 

DESCRIPTION 

These  functions  convert  a  string  pointed  to  by  nptr  to  floating,  integer,  and  long  integer  repre8en> 
tatioh  respectively.  The  first  unrecognized  character  ends  the  string. 

Atof  recognizes  an  optional  string  of  spaces,  then  an  optional  sign,  then  a  string  of  digits  option¬ 
ally  containing  a  decimal  point,  then  an  optional  ‘e’  or  ‘E’  followed  by  an  optionally  signed 
integer. 

Atoi  and  atot  recognize  an  optional  string  of  spaces,  then  an  optional  sign,  then  a  string  of  digits. 
SEE  ALSO 

scanf(3S) 

BUGS 

There  are  no  provisions  for  overflow. 

Currently,  atof  performs  highly  inaccurate  conversions  of  very  large  or  very  smaU  numbers  —  on 
the  order  of  10**32  or  its  reciprocal. 


o 
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BSTRING(3) 


SUBROUTINES 


BSTRING(3) 


NAME 

bcopy,  bcmp,  bzero,  ffs  -  bit  and  byte  string  operations 
SYNOPSIS 

bcopy(bl,  bS,  length) 
char  *bl,  *b2| 
tnt  length; 

bemp(bl,  bS,  length) 
char  *bl,  '*b9; 

Int  length; 

bMro(h|  length) 
char  *'b; 

Int  length; 

m) 

Int  1; 

DESCRIPTION 

The  functions  beopjf,  hemp,  and  hztro  operate  on  variable  length  strings  of  bytes.  They  do  not 
check  for  null  bytes  as  the  routines  in  slrfnp(3)  do. 

Bcopy  copies  tensth  bytes  from  string  hi  to  the  string  hS. 

Betnp  compares  byte  string  hi  against  byte  string  h2,  returning  zero  if  they  are  identical,  non>zero 
otherwise.  Both  strings  are  assumed  to  be  length  bytes  long. 

Bzero  places  length  0  bytes  in  the  string  (. 

Ffe  finds  the  first  bit  set  in  the  argument  passed  it  and  returns  the  index  of  that  bit.  Bits  are 
numbered  starting  at  1  from  the  right.  A  return  value  of  -1  indicates  the  value  passed  is  zero. 

BUGS 

The  hemp  an<[  heopg  routines  take  parameters  backwards  from  stremp-and  strepg. 
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CRYPT(3) 


SUBROUTINES 


CRYPT  (3) 


NAME 

crypt,  setkey^  encrypt  -  DES  enctyption 
SYNOPSIS 

char  *erypt(key,  salt) 
char  *key,  *aatt| 

setkey(key) 
char  *keyt 

enerypt(bIoeky  «dflag) 
char  *bloek| 

DESCRIPTION 

Crypt  is  the  password  encryption  routine.  It  b  based  on  the  NBS  Data  Encryption  Standard,  with 
variations  intended  (among  other  things)  to  frustrate  use  of  hardware  implementations  of  the  DES 
for  key  search. 

The  first  argument  to  crypt  b  normally  a  user’s  typed  password.  The  second  b  a  2^haracter 
string  chosen  from  the  set  [arzA-ZO^fi./].  The  talt  string  b  used  to  perturb  the  DES  algorithm  in 
one  of  4006  different  ways,  after  which  the  password  is  used  as  the  key  to  encrypt  repeatedly  a 
constant  string.  The  returned  value  points  to  the  encrypted  password,  in  the  same  alphabet  as 
the  salt.  The  first  two  characters  are  the  salt  itself. 

The  other  entries  provide  (rather  primitive)  access  to  the  actual  DES  algorithm.  The  argument  of 
eetkey  is  a  character  array  of  length  64  containing  only  the  characters  with  numerical  value  0  and 
1.  If  thb  string  is  divided  into  groups  of  8,  the  Iow>order  bit  in  each  group  b  ignored,  leading  to 
a  66>bit  key  which  b  set  into  the  machine. 

The  argument  to  the  encrypt  entry  b  likewise  a  character  array  of  length  64  containing  O's  and 
I's.  The  argument  array  is  modified  in  place  to  a  similar  array  representing  the  bits  of  the  argu¬ 
ment  after  having  been  subjected  to  the  DES  algorithm  using  the  key  set  by  eetkey.  If  edfiag  is  0, 
the  argument  is  encrypted;  if  non-zero,  it  b  decrypted. 

SEE  ALSO 

pa8swd(l),  passwd(S),  login(l),  getpa88(3) 

BUGS 

The  return  value  points  to  static  data  whose  content  b  overwritten  by  each  call. 
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CTIME(3) 


SUBROUTINES 


CTIME(3) 


NAME 

ctime,  Io«altime,  gmtime,  asctime,  tim^zone,  dysize  -  convert  date  and  time  to  ASCII 

SYNOPSIS 

char  *ctlne(cloek) 
long  *eloekt 

^include  <8ys/tlmeJi> 

atruet  tm  *IoealtIme(elock) 
long  *eloek^ 

atruet  tm  *gmtlme(eIoek) 
long  *cloek| 

char  *aactlme(tm) 
atruet  tm  *tmr 

ehar  *tlmeione(aon«f  dat) 

Int  dyalie^ 

Int  y» 

DESCRIPTION 

Ctime  converts  a  time  pointed  to  by  dock  sncb  as  returned  by  geUimeofday{2)  into  ASCII  and 
returns  a  pointer  to  a  26<baracter  string  in  the  following  form.  All  the  fields  have  constant 
width. 

Sun  Sep  16  01:03:52  1973\n\0 

Loealtime  and  gmtime  return  pointers  to  structures  containing  the  broken-down  time.  Loealtime 
corrects  for  the  time  zone  and  possible  daylight  savings  time;  gmtime  converts  directly  to  GMT, 
which  is  the  time  UNIX  uses.  Aactime  converts  a  t»oken-down  time  to  ASCII  and  returns  a 
pointer  to  a  26*character  string. 

The  structure  declaration  from  the  include  file  is: 


struct  tm  { 
lot 

tmjwc; 

int 

tm_!nin; 

int 

tmjiour; 

int 

tm^day; 

int 

tm_pion; 

int 

tm_year; 

int 

•  tm_wday; 

int 

tm_ydsor- 

int 

tmjisdst; 

)r 

These  qieantities  give  the  time  on  a  24-hoiir  c!bek«  day  of  month  (1*%),  month  of  year  (0*11),  day 
of  week  (Sunday  ^  0),  year  -  1900^  ds^  of  year  (0-35^,  and  a  flag  that  b  nonzero  if  di^Hght  sav* 
ing  time  is  in^effect. 

When  local  iime  is  cafled  for,  the  program  consults  the  system  to  detettmne  the  time  zone  and 
whether  the  Australian,  Eastern  European,  Middle  European,  or  Western  European  day¬ 

light  saving  time  adjustment  is  appropriate.  The  program  knows  about  various  pecuUarities  in 
time  conversion  over  the  ^ast  10-20  years. 

Timtzont  returns  tne  name  of  the  time  zone  associated  with  its  first  argument,  which  is  measured 
in  minutes  westward  from  Greenwich.  If  the  second  argument  is  0,  the  standard  name  is  used, 
otherwise  the  Daylight  Saving  version.  If  the  required  name  does  not  appear  in  a  table  built  into 
the  routine,  the  difference  from  GMT  is  produced;  e.g.  in  Afghanistan  timtzon€(-(60^4’^  SO),  0)  is 
appropriate  because  it  is  4:30  ahead  of  GMT  and  the  string  GMT+4:30  is  produced. 
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CTIME(3) 


SUBROUTINES 


CTIME(3) 


Dyeizt  returns  the  number  of  da^s  in  the  argument  year,  either  365  or  366. 

SEE  ALSO 

gettimeofday(2),  time(3C) 

BUGS 

The  return  values  point  to  static  data  whose  content  is  overwritten  by  each  call. 
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CTYPE(3) 


SUBROUTINES 


CTYPE(3) 


NAME 

isalpha,  isupper,  islower,  isdigit,  isxdigit,  isalnum,  isspace,  ispunct,  isprint,  iscntrl,  isascii,  is^aph, 
toupper,  tolower,  toascii  -  character  classification  and  conversion  mactos 

SYNOPSIS 

#lnelude  <ctypeJi> 
balpha(e) 


COARACTER  CLASSIFICATION  MACROS 

These  macros  classify  ASCII-coded  integer  values  by  table  lookup.  Bach  »  a  predicate  retnrning 
nonzero  for  true,  zero  for  false,  /sasculis  defined  on  all  integer  vafaies;  the  rest  are  defined  only 
where  i8aBcii(c)  is  true  and  on  the  singfe  non-ASCII  value  EOF  (see  sfdio(3S)). 

isalpha(c)  c  is  a  tetter 

i8upper(c)  c  is  an  tq>per  case  letter 

isIowet(c)  e  fs  a  lower  case  letter 

isdigtt(c)  cisad^it 

isxdigit(e)  c  is  a  hexadecimal  digit 

i6alnum(e)  c  is  an  alphanumeric  character 

is8pace(e)  e  is  a  space,  tab,  carriage  return,  newline,  or  formfeed 

i8pttnct(e)  e  is  a  punctuation  character  (neither  control  nor  alphanumeric) 

i8print(c)  c  is  a  printing  character,  code  040(8)  (space)  through  0176  (tilde) 

iscntrl(c)  c  is  a  delete  character  (0177)  or  ordinary  control  character  (less  than  040). 

i8a8cii(e)  c  is  mi  ASCII  character,  code  less  than  0200 

i8graph(c)  c  is  a  visible  graphic  character,  code  041  (exclamation  martc)  through  0176  (tilde). 

OHARAOTBR  CONVERSION  MACROS 

These  macros  perform  simple  conversions  on  single  characters. 

tonpper(e)  converts  c  to  its  upper-case  equivalent.  Note  that  thb  only  works  where  e  is 
known  to  be  a  lower-case  character  to  start  with  (presumably  checked  via 
ulower). 

toIower(c)  converts  c  to  its  lower-case  equivalent.  Note  that  this  artip  works  wheio  e  is 
known  to  be  a  upper-case  character  to  start  with  (presumably- checked  via 
ifupptr). 

toa8cii(c}  masks  e  with  the  cmiect  value  so  that  e  is  guaranteed  Co  be  an  ASCII  character 

in  the  range  0  thru  0x7L 


SEE  ALSO 

ascii(7) 
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DIRECT0RY(3) 


SUBROUTINES 


DIRECTORY(3) 


NAME 

opendir,  readdir,  telldir,  seekdir,  rewinddir,  closedir  -  directory  operations 
SYNOPSIS 

#lnelude  <ByB/db'.h> 

DIR  *opendir(fllename) 
chsir 

ftruet  direct  *readdtr(dlrp) 
piRMlrpt 

long  teUdlr(dlrp) 

DIR  *dlrpi 

seekdir(dlrp»  loe) 

DIR  Mirpi 
long  locf 

rewinddir  (dlrp) 

DIR  *dlrp; 

eloiedlr(dIrp) 

DIR  •dlrpt 

DESCRIPTION 

Op  eniir  opens  the  directory  named  by  filename  and.  associates  a  directory  etream  with  it.  Opendir 
returns  a  pointer  to  be  used  to  identify  the  directory  etream  in  subsequent  operations.  The 
pointer  NULL  is  returned  if  filename  cannot  be  accessed  or  is  not  a  directory,  or  if  it  cannot  mal- 
/oc(3)  enough  memory  to  hold  the  whole  thing. 

Readdir  returns  a  pointer  to  the  next  directory  entry.  It  returns  NULL  upon  reaching  the  end  of 
the  directory  or  detecting  an  invalid  teekdir  operation. 

Telldir  returns  the  current  location  associated  with  the  named  directory  etream. 

Seekdir.  sets  the  position  of  the  next  readdir  operation  on  the  directory  etream.  The  new  position 
reverts  to  the  one  associated  with  the  directory  etream  when  the  telldir  operation  was  performed. 
Values  returned  by  telldir  are  good  only  for  the  lifetime  of  the  DIR  pointer  from  which  they  are 
derived.  If  the  directory  is  closed  and  then  reopened,  the  telldir  value  may  be  invalidated  due  to 
undetected  directory  compaction.  It  is  safe  to  use  a  previous  teUdir  value  immediately  after  a  caU 
to  opendir  and  before  any  calls  to  readdir. 

Rewinddir  resets  the  position  of  the  named  directory  etream  to  the  beginning  of  the  directory. 

Cloeedir  closes  the  named  directory  etream  and  frees  the  structure  associated  with  the  DIR 
pointer) 

Sample  code  which  searchs  a  <iirectoiy  for  entry  “name”  is: 

len  =>  strlen(name); 
dirp  =  opendir(".”); 

for  (dp  =  readdir(dirp);  dp  !=  NULL;  dp  =  readdir(dirp)) 

if  (dp->d_namlen  ==*  len  &&  !strcmp(dp>>djBame,  name))  { 
closedir(dirp); 
return  FOUND; 

} 

closed  ir(dirp); 
return  NOT_FOUND; 

SEE  ALSO 

open(2),  close(2),  read(2),  lseek(2),  dir(5) 
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DIRECT0RY(3) 


SUBROUTINES 


DIRECTORY  (3) 


BUQS^ 

Old  UNIX  programs  which  examioe  directories  should  be  converted  to  use  this  package,  as  the 
new  directory  format  is  non-obvious. 


o 
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ECVT(3) 


SUBROUTINES 


ECVT(3) 


NAME 

ecvt,  fcvt,  gcvt  -  ciutput  conversion 
SYNOP|?IS 

ehar  *eevt(va!ue»  ndlglt,  deept,  sign) 
double  value) 

Ipt  ndlglt,  *decpt,  *slgn) 

char  *fevt(value»  ndlgitf  deept,  sign) 
double  value) 

Int  ndlglt,  Meept,  *slgn) 

char  *gcvt(valuei  ndlglt,  buf) 
double  value) 
char  *buf) 

DESCRIPTION 

Ecvt  converts  the  vaiue  to  a  nuU-terminated  string  of  ndigit  ASCII  digits  and  returns  a  pointer 
thereto.  The  position  of  the  decimal  point  relative  to  the  beginning  of  the  string  is  stored 
indirectly  through  deept  (negative  means  to  the  left  of  the  returned  digits).  If  the  sign  of  the 
result  is  negative,  the  word  pointed  to  by  tign  is  non>zero,  otherwise  it  is  zero.  The  low-order 
digit  is  rounded. 

F evt  is  identical  to  ecvt,  except  that  the  correct  digit  has  been  rounded  for  Fortran  F-format  out¬ 
put  of  the  number  of  digits  specified  by  ndigita. 

Gcvt  converts  the  value  to  a  null-terminated  ASCII  stoing  in  buf  and  returns  a  pointer  to  buf.  It 
attempts  to  produce  ndigit  significant  digits  in  Fortran  F  format  if  possible,  otherwise  E  format, 

.  ready  for  printing.  Trailing  zeros  may  be  suppressed. 

SEE  aLso 

isinf(3),  printf(3S) 

Buai^ 

The  return  values  point  to  static  data  whose  content  is  overwritten  by  each  call. 
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END(3) 


SUBROUTINES 


END(3) 


NAME 

end,  etext,  edata  ^  last  locations  in  program 

SYNOPSIS 

extern  end} 
extern  etextf 
extern  edata} 

DESCRIPTION 

These  nsones  refer  neither  to  routines  nor  to  locations  with  interesting. eealents.  The  address  of 
eterf  is  the  first  address  above  the  program  text,  edata  above  the  initialized  data  region,  and  end 
above  the  uninitialized  data  region. 

When  execntion  begins,  the  program  break  coincides  with  end,  but  it  is  reset  by  the  routines 
hrk{2),  maWffe(3),  standard  input/output  (ff{dte(3S)),  the  profile  (-p)  option  ot  ec(l)^  etc.  The 
current  value  ot  the  program  break  is  relia^  returned  by  ‘sbric(O)’,  see  brk(2). 

SEE  ALSO 

brk(2),  malloc(3) 


o 


o 
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EXECL(3) 


SUBROUTINES 


EXECL(3) 


NAME 

execl,  execv,  execle,  execlp,  execvp,  environ  -  execute  a  file 
SYNOPSIS 

execl(name,  argO,  argl, argn,  0) 
char  *Dam«,  *argO,  *argl,  .../*argn| 

execv(name,  argv) 
char  *name»  *argv[  ]{ 

exeele(name,  argO,  argl,  argn,  0»  envp) 
char  ^nainc^  *argO(  *arglt  uaf  ^argot  *envp(  ]i 

exeelp(name,  argO,  argl|  Argn,  0^  envp) 
char  ^name,  *argOt  *arglt  *Mgn,  *envp[  ]} 

exeevp(name»  argVy  envp) 
char  ^namet  *argv(  ],  ♦envp[]i 

extern  char  **envlron^ 

DESCRIPTION 

These  routines  provide  various  interfaces  to  the  execve  system  call.  Refer  to  exect;e(2)  for  a 
description  of  their  properties;  only  brief  descriptions  arc  provided  here. 

Exec  in  all  its  forms  overlays  the  calling  process  with  the  named  file,  then  transfers  to  the  entry 
point  of  the  core  image  of  the  file.  There  can  be  no  return  from  a  successful  exec;  the  calling  core 
image  is  lost. 

The  name  argument  is  a  pointer  to  the  name  of  the  file  to  be  executed.  The  pointers  arg[0], 
arg\l\ ...  address  nu!l>terminated  strings.  Conventionally  arg\0\  is  the  name  of  the  file. 

Two  interfaces  are  available,  excel  is  useful  when  a  known  file  with  known  arguments  is  being 
called;  the  arguments  to  excel  are  the  character  strings  constituting  the  file  and  the  arguments; 
the  first  argument  is  conventionally  the  same  as  the  file  name  (or  its  last  component).  A  0  argu¬ 
ment  must  end  the  argument  list. 

The  excev  version  is  useful  when  the  number  of  arguments  is  unknown  in  advance;  the  arguments 
to  execv  are  the  name  of  the  file  to  be  executed  and  a  vector  of  strings  containing  the  arguments. 
The  last  argument  string  must  be  followed  by  a  0  pointer. 

When  a  C  program  is  executed,  it  is  called  as  follows: 

main(argc,  argv,  envp) 
int  arge; 

char  **argv,  **envp; 

where  arge  is  the  argument  count  and  argv  is  an  array  of  character  pointers  to  the  arguments 
themselves.  As  indicated,  arge  is  conventionally  at  least  one  and  the  first  member  of  the  array 
points  to  a  string  containing  the  name  of  the  file. 

Argv  is  directly  usable  in  another  execv  because  argv[arge\  is  0. 

Envp  is  a  poinfer  to  an  array  bf  strings  that  cohstitute  the  environment  of  the  process.  Each 
string  consists  of  a  name,  an  ''s”,  and  a  null*^terminated  value.  The  array  of  pointers  is  ter¬ 
minated  by  a  null  pointer.  The  shell  r^(l)  passes  an  environment  entry  for  each  global  shell  vari¬ 
able  defined  when  the  program  is  called.  See  envtron(5)  for  some  conventionally  used  names. 
The  C  run-time  start-off  routine  places  a  copy  of  envp  in  the  global  cell  environ,  which  is  used  by 
execv  and  execl  to  pass  the  environment  to  any  subprograms  executed  by  the  current  program. 

Execlp  and  execvp  are  called  with  the  same  arguments  as  exeel  and  execv,  but  duplicate  the  skeirs 
actions  in  searching  for  an  executable  file  in  a  list  of  directories.  The  directory  list  is  obtained 
from  the  environment. 
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EXECL(3) 


SUBROUTINES 


EXECL(3) 


FILES 

/bin/Bh  shell,  invoked  if  command  file  found  by  execlp  or  exeevp 
SEE  ALSO 

execve(2),  fork(2),  environ(5),  csh(l),  sh(l) 

"UNIX  Programming"  in  Programming  Tools  for  the  SUN  Workstatiot^  pp.  1-3. 

DIAGNOSTICS 

If  the  file  cannot  be  found,  if  it  is  not  executable,  if  it  docs  not  start  with  a  valid  magic  number 
(see  a.oul(5)),  if  maximum  memory  is  exceeded,  or  if  the  arguments  require  too  much  space,  a 
r^pturn  constitutes  the  diagnostic;  the  return  value  is  —1.  EJven  for  the  super- user,  at  least  one  of 
the  execute-permission  bits  must  be  set  for  a  file  to  be  executed. 

BUGS 

If  eaect^  is  caUed  to  execute  a  file  that  turns  out  to  be  a  shell  command  file,  and  if  it  is  impossi¬ 
ble  to  execute  the  shell,  the  values  of  argvfO}  and  argv[~l}  will  be  modified  before  return.. 
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EXIT(3) 


SUBROUTINES 


NAME 

exit  -  tenninate  a  process  after  flushing  any  pending  output 

SYNOPSIS 

extt(status) 

Int  status} 

DES0RH»T10N 

Exit  terminates  a  process  by  calling  exit{2)  after  calling  the  Standard 
^cleanup  to  flush  any  buffered  output.  Exit  never  returns. 

SEE  ALSO 

exit(2),  intro(3S) 
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I/O  library  function 
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SUBROUTINES 


FREXP(3) 


NAME 

frexp,  Idexp,  modf  -  split  into  mantissa  and  exponent 
SYNOPSIS 

double  frexp(v«lu«)  eptr) 
double  veluei 
Int  ^eptri 

double  ldexp(v«lue,  exp) 
double  value} 

double  modf(vatue»  Iptr) 
double  value*  *iptrt 

DESCRIPTION 

Frexp  returns  the  mantissa  of  a  double  value  as  a  double  quantity,  x,  of  magnitude  less  than  1  and 
stores  an  integer  n  such  that  value  =  **2”  indirectly  through  eptr. 

Ldexp  returns  the  quantity  value* 

Maif  returns  the  positive  fractional  part  of  value  and  stores  the  integer  part  indirectly  through 
iptr. 

SEE  ALSO 

i8inf(3) 

BUGS 

The  identity  claimed  for  the  results  of  frexp  cannot  hold  when  the  value  argument  is  an  IEEE 
indefinite  quantity  —  infinity  or  no^a-number. 
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GETDATE(3) 


StJBROUTINES 


GETDATE(3) 


NAME 

getdate  -  convert  time  and  date  from  ASCH 

SYNOPSIS 

#iiiclude  <ays/typeB.h> 

#lnclude  <ayB/timeb.h> 

getdate(buf|  now) 
char  '^buf| 

struct  timeb  *now; 

DESCRIPTION 

Get  date  converts  most  common  time  specifications  to  standard  UNIX  format.  The  first  argument 
is  the  character  string  containing  the  time  and  date;  the  second  is  the  assumed  current  time  (used 
for  relative  specifications);  if  NULL  is  passed^  SHmt(2)  is  used  to  obtain  the  current  time  and 
timezone. 

The  character  string  consists  of  0  or  more  specifications  of  the  following  form: 

tod  A  fed  is  a  time  of  day,  which  is  of  the  form  hk:mm\:9$\  (or  khmm)  [mendjan}  [zone].  If 
no  meridian  -  am  or  pm  -  is  specified,  a  24-hour  clock  b  used.  A  tod  m^  be  specified  as 
just  hh  followed  by  a  meridian. 

date  A  date  is  a  specific  month  and  day>  and  possibly  a  year.  Acceptable  formats  are 
mm/dd[/yy]  and  monthname  ddj,  yy]  If  omitted,  the  year  defaults  to  the  current  year;  if  a 
year  b  specified  as  a  number  less  than  100,  1900  is  added.  If  a  number  not  followed  by  a 
day  or  relative  time  unit  occurs,  it  will  be  interpreted  as  a  year  if  a  lod,  monthname,  and 
dd  have  already  been  specified;  otherwise,  it  will  be  treated  as  a  tod.  Thb  rule  allows  the 
output  from  do^c(l)  or  c(jme(3)  to  be  passed  as  input  to  getdate. 

day  A  day  of  the  week  may  be  specified;  the  current  day  will  be  used  if  appropriate.  A  day 
may  be  proceeded  by  a  number,  indicating  which  instance  of  that  day  b  desired;  the 
default  b  1.  Negative  numbers  indicate  times  past.  Some  symbolic  numbers  are 
accepted:  Imst,  next,  and  the  ordinab  first  through  twelfth  (second  b  ambiguous,  and 
is  not  accepted  as  an  ordinal  number).  The  symbolic  number  next  b  equivalent  to  2; 
thus,  next  monday  refers  not  to  the  immediately  coming  Monday,  but  to  the  one  a  week 
later. 

relative  time 

Specifications  relative  to  the  current  time  are  also  accepted.  The  format  is  [number]  uni^; 
acceptable  units  are  year,  month,  fortnight,  wssk,  day,  hour,  mlnuto,  and  second. 

The  actual  date  b  formed  as  follows:  first,  any  absolute  date  and/or  time  is  processed  and  con¬ 
verted.  Using  that  time  as  the  base,  day-of-week  specifications  are  added;  last,  relative 
specifications  are  used.  If  a  date  or  dzy  b  specified,  and  no  absolute  or  relative  time  b  given, 
midnight  is  used.  Finally,  a  correction  is  applied  so  that  the  correct  hour  of  the  day  is  produced 
after  allowing  for  daylight  savings  time  differences. 

Getdate  accepts  most  common  abbreviations  for  days,  months,  etc.;  in  particular,  it  recognizes 
them  with  upper  or  lower  case  first  letter,  and  recognizes  three-letter  abbreviations  for  any  of 
them,  with  or  without  a  trailing  period.  Units,  such  as  weeks,  may  be  specified  in  the  singular  or 
plural.  Timezone  and  meridian  values  may  be  in  upper  or  lower  case,  and  with  or  without 
periods. 

FILES 

/usr/Iib/libu.a 

SEE  ALSO 

etime(3),  time(2) 
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BUGS 

Because  jfacc(l)  is  used  to  parse  the  date,  gefdaie  cannot  be  used  a  subroutine  to  any  program 
that  also  needs  yaee. 

The  grammar  and  scanner  are  rather  primitive;  certain  desirable  and  unambiguous  constructions 
are  not  accepted.  Worse  yet,  the  meaning  of  some  legal  phrases  is  not  what  is  expected;  next 
week  is  identical  to  S  weeke. 

The  daylight  savings  time  correction  is  not  perfect,  and  can  get  confused  if  handed  times  between 
midnight  and  2:00  am  on  the  days  that  the  reckoning  changes. 

Because  toealHme{2)  accepts  an  oId>styIe  time  format  without  zone  information,  attempting  to 
pass  getdate  a  current  time  containing  a  different  zone  will  probably  fail. 
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GETENV(3) 


SUBROUTINES 


GETENVO) 


NAME 

getenv  -  value  for  environment  name 

SYNOPSIS 

char  *getenv(name) 
chnr  *name} 

DESCRIPTION 

Getenv  searches  the  environment  list  (see  entnron{5))  for  a  string  of  the  form  name^vatue  and 
returns  a  pointer  to  the  string  value  if  such  a  string  is  present,  otherwise  getenv  returns  the  value 
0  (NULL). 

SEE  ALSO 

environ(5),  execve(2) 
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GETFSENT(3) 


o 


NAME 

getfsent,  g«tfs6p«c,  getfsfile,  getfstype,  setfsent,  endfsent  -  get  file  system  descriptor  file  entry 

SYNOPSIS 

#lne!ude  <fstab.h> 

•truet  fiitab  *getfaeiit() 

struct  fstab  *g«tfiupee(spee) 
char  *spee| 

struct  fitab  *getfsflle(file) 
char 

struct  fitab  *getfstype(typs) 
char  *type| 

Int  setfsentO 
Int  endflientO 
DESCRIPTION 

Getftent,  getfsBpee,  getfatype,  and  get/aJUe  each  return  a  pointer  to  an  object  with  the  following 
structure  containing  the  broken-out  fields  of  a  line  in  the  file  system  description  file,  <f8tab.b>. 


struct  fstab  { 

char 

♦fs^spec; 

char 

♦fsjlc; 

char 

•fs^type; 

int 

fs_^frcq; 

int 

fs^passno; 

); 

The  fields  have  meanings  described  in  /rlaS(5). 

Getfsent  reads  the  next  line  of  the  file,  opening  the  file  if  necessary. 

Setfsent  opens  and  rewinds  the  file. 

Enifsent  closes  the  file. 

Getfaspee  and  getfsfile  sequentially  search  from  the  beginning  of  the  file  until  a  matching  special 
file  name  or  file  system  file  name  is  found,  or  until  EOF  is  encountered.  Getfatype  does  likewise, 
matching  on  the  file  system  type  field. 

FILES 

/etc/&tab 

SEE.  ALSO 

r8tab(5) 

DIAGNOSTICS 

Null  pointer  (oyretnrned  on.  EOF  or  etrew; 

BUGS 

The  return  value  points  to  static  information  which  is  overwritten  in  each  caS. 
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SUBROUTINES 


GETGRENT(3) 


NAME 

getgrent,  getgrgid,  getgrnam,  setgrent,  endgrent  -  get  group  file  entry 

SYNOPSIS 

#lnelude  <grp.h> 

struct  group  *getgrentQ 

struct  group  *getgrgtd(gi<l) 

Int  gld) 

struct  group  *getgrnam(name) 
char  *nam«) 

setgrentO 

«ndgrent() 

DESCRIPTION 

Getgrent,  getgrgid  and  getgrnam  each  return  pointers  to  an  object  with  the  following  structure 
containing  the  broken>out  fields  of  a  line  in  the  group  file: 

struct  group  { 

char  *gr_naine; 
char  *gr_pa88wd; 
int  gr_gid; 
char  **gr_pnein; 

}; 

The  members  of  this  structure  are: 

gr_name  The  name  of  the  group. 
gr_passwd  The  encrypted  password  of  the  group. 
gr_gid  The  numerical  group-lD. 

gr_mem  Null-terminated  vector  of  pointers  to  the  individual  member  names. 

Getgrent  simply  reads  the  next  line  while  getgrgid  and  getgrnam  search  until  a  matching  gid  or 
name  is  found  (or  until  EOF  is  encountered).  Each  routine  picks  up  where  the  others  leave  off  so 
successive  calls  may  be  used  to  search  the  entire  file. 

A  call  to  eetgrent  has  the  effect  of  rewinding  the  group  file  to  allow  repeated  searches.  Endgrent 
may  be  called  to  close  the  group  file  when  processing  is  complete. 

FILES 

/etc/group 
SEE  ALSO 

ge(login(3),  getpwent(3),  group(5) 

DIAGNOSTICS 

A  null  pointer  (0)  is  returned  on  EOF  or  error. 

BUGS 

The  return  value  points  to  static  information  which  is  overwritten  on  each  call. 
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NAME 

getlogin  -  get  login  name 

SYNOPSIS 

char  ^getloginQ 

DESCRIPTION 

Getlogin  returns  a  pointer  to  the  login  name  as  found  in  j  etcjutmp*  It  may  be  used  in  conjunc* 
tion  with  getpwnam  to  locate  the  correct  password  file  entry  when  the  same  userid  is  shared  by 
several  login  names. 

If  getlogin  is  called  within  a  process  that  is  not  attached  to  a  typewriter,  it  returns  NULL.  The 
correct  procedure  for  determining  the  login  name  is  to  first  call  getlogin  and  if  it  fails,  to  call 
^elpwuid(^eluid()). 

FILES 

/etc/utmp 
SEE  ALSO 

getpwent(3),  getgrent(3)|  utmp(5) 

DIAGNOSTICS 

Returns  NULL  (0)  if  name  not  found. 

BUGS 

The  return  values  point  to  static  data  whose  content  is  overwritten  by  each  call. 

Getlogin  does  not  work  for  processes  running  under  a  pty  (for  example,  emacs  shell  buffers,  or  shell 
tools)  unless  the  program  'Takes”  the  login  name  in  the  fetclutmp  file. 
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SUBROUTINES 


GETPASS(3) 


NAME 

getpass  -  read  a  pusword 
SYNOPSIS 

char  *getpan(prompt) 
char  *prompt} 

DESCRIPTION 

Getpaet  reads  a  password  from  the  file  Idev/Uy,  or  if  that  cannot  be  opened,  from  the  standard 
input,  after  prompting  with  the  nulbterminated  string  prompt  and  disabling  echoing.  A  pointer  is 
returned  to  a  null>terminated  string  of  at  most  8  characters. 

FILES 

/dev/t(y 

SEE  ALSO 

crypt(3) 

BUGS 

The  return  value  points  to  static  data  whose  content  is  overwritten  by  each  call. 
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GETPW(3) 


NAME 

getpw  -  get  name  from  uid 

SYNOPSIS 

getpw(uld,  buf) 
ehar  *bttfl 

DESCRIPTION 

Gntpw  in  obnoletnd  by  getpwent(3). 

Getpto  searches  the  password  file  for  the  (numericsd)  tiid,  and  fills  in  buf  with  the  corresponding 
line;  it  returns  non-zero  if  tiid  could  not  be  found.  The  line  is  null-terminated. 

FILES 

/ete/passwd 

SEE  ALSO 

getpwent(3),  pa8swd(5) 

DIAGNOSTICS 

Non-zero  return  on  error. 


o 
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GETWD(3) 


NAME 

getwd  -  get  current  working  directory  pathname 
SYNOPSIS 

#lnelade  <8yn/param.h> 

char  *getwd(pathname) 

ehar  pathname[MAXPATHLEN]{ 

DESCRIPTION 

Getwd  copies  the  absolute  pathname  of  the  current  working  directory  to  pathname  and  returns  a 
pointer  to  the  result. 

DIAGNOSTICS 

Getwd  returns  zero  and  places  a  message  in  pathname  if  an  error  occurs. 

BUGS 

Getwd  may  fail  to  return  to  the  current  directory  if  an  error  occurs. 
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NAME 

initgrottps  -  initialize  group  access  list 
SYNOPSIS 

liiItgroupi(n»ine,  bnaegld) 
char  *name) 

Int  basegid} 

DESCRIPTION 

Initgroups  reads  through  the  group  file  and  sets  up,  using  the  8etgr6ups{2)  call,  the  group  access 
list  for  the  user  specified  in  name.  The  iaeegid  is  automatically  included  in  the  groups  list.  Typi¬ 
cally  this  value  is  given  as  the  group  number  from  the  password  file. 

FILES 

/etc/group 

SEE  ALSO 

Betgroup8(2) 

DIAGNOSTICS 

Initgroupe  returns  -1  if  it  was  not  invoked  by  Che  supei^ttser. 

BUGS 

Jnitgroupe  uses  the  routines  based  on  getgrent{3).  If  the  invoking  program  uses  any  of  these  rou¬ 
tines,  the  group  structure  will  be  overwritten  in  the  call  to  initgroupe. 

Noone  seems  to  keep  /etc/group  up  to  date. 
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SUBROUTINES 


INSQUE(3) 


NAME 

insque,  remque  -  msert/remove  element  from  n  queue 

SYNOPSIS 

utruet  qelem  { 

struct  qelem  *qjforw| 
struct  qelem  ^qjbacki 
char  q_dataQ| 

}l 

inBque(eIem|  pred) 
struct  qelem  ^elemp  *pred| 

remque(elem) 
struct  qelem  ^elemi 

DESCRIPTION 

Insque  and  remque  manipulate  queues  built  from  doubly  linked  lists.  Each  element  in  the  queue 
must  be  in  the  form  of  "struct  qelem".  Insque  inserts  elem  in  a  queue  imediately  after  pred; 
rcmguc  removes  an  entry  efem  from  a  queue. 

SEE  ALSO 

"VAX  Architecture  Handbook pp.  228-235.  It  does  work  on  SUNS. 
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NAME 

isinf,  isDan  -  test  for  indeterminate  fioating  point  values 

SYNOPSIS 

Int  blnf(value) 
double  value} 

Int  bnan(value) 
double  v^ue} 

DESCRIPTION 

lait^  returns  a  value  of  1  if  Its  value  is  an  IEEE  format  infinity  (two  words  0x7800000 
0x00000000)  or  an  IEEE  negative  infinity,  and  returns  a  zero  otherwise. 

lenan  returns  a  value  of  1  if  its  value  is  an  IEEE  format  'not-a-number’  (two  words 
0x78  nnnnnOx  nnnnnnnn)  where  n  is  not  zero)  or  its  negative,  and  returns  a  zero  otherwise. 

Some  library  routines  such  as  ecv<(3)  do  not  handle  indeterminate  floating  point  values  gracefully. 
Prospective  arguments  to  such  routines  should  be  checked  with  iainf  or  iman  before  calling  these 
routines. 

BUGS 

Need  a  manual  section  describing  the  format  of  1E£E  numbers  in  detail. 
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NAME 

malloc,  free,  realloc,  calloc,  cfree,  alloca  -  memory  allocator 

SYNOPSIS 

char  *maIloe(8Ue) 
unsigned,  slsei 

f^ee(ptr) 
char  *ptri 

char  *reaUoe{ptr,  sin) 
char  *ptr} 
unsigned  sisei 

char  *caUoe(neiein,  elslse) 
unsigned  neletn,  elsisei 

eft>ee(ptr) 
char  *pir} 

char  *aUoca(stie) 

Int  sise) 

malloc jok(slse) 
int  siset 

DESCRIPTION 

Malloc  and  /ree  provide  a  general-purpose  memory  allocation  package.  Mai/oc  returns  a  pointer  to 
a  block  of  at  least  size  bytes  beginning  on  a  word  boundary. 

The  argument  to  free  is  a  pointer  to  a  block  previously  allocated  by  malloc;  this  space  is  made 
available  for  further  allocation,  but  its  contents  are  left  undisturbed. 

Needless  to  say,  grave  disorder  will  result  if  the  space  assigned  by  matloe  is  overrun  or  if  some 
random  number  is  handed  to  free. 

Malloc  maintains  a  cartesian  tree  of  free  blocks.  It  calls  sir*  (see  ir*(2))  to  get  more  memory 
from  the  system  when  there  is  no  suitable  space  already  free. 

Realloc  changes  the  size  of  the  block  pointed  to  by  ptr  to  sise  bytes  and  returns  a  pointer  to  the 
(possibly  moved)  block.  The  contents  will  be  unchanged  up  to  the  lesser  of  the  new  and  old  sizes. 

R  ealloc  also  works  if  ptr  points  to  a  block  freed  since  the  last  call  of  malloc,  realloe  or  calloc. 

Calloc  allocates  space  for  an  array  of  nelem  elements  of  size  elsize.  The  space  is  initialized  to 
zeros,  and  can  be  freed  with  cfree. 

Alloca  ^locates  size  bytes  of  space  in  the  stack  frame  of  the  caller.  This  temporary  space  is 
automatically  freed  on  return. 

Ocassionally  a  program  will  overun  the  storage  allocated  from  Malloc  .  Malloe_ok  helps  determine 
when  this  has  happened.  It  checks  all  blocks  (free  or  allocated)  looking  for  duplicates,  strange 
addresses  and  absurd  sizes.  Malloc^ok  returns  true  if  everything  is  is  found.  The  size  parameter 
specifies  the  maximum  acceptable  size  of  a  block.  A  block  with  a  larger  size  is  considered  bad.  If 
size  is  zero  a  maximum  of  10000  is  assumed. 

Each  of  the  allocation  routines  returns  a  pointer  to  space  suitably  aligned  (after  possible  pointer 
coercion)  for  storage  of  any  type  of  object. 

SEE  ALSO 

F ast  Fits  by  C.  J.  Stephenson 
DIAGNOSTICS 

Malloc,  realloe  and  calloc  return  a  null  pointer  (0)  if  there  is  no  available  memory  or  if  the  arena 
has  been  detectably  corrupted  by  storing  outside  the  bounds  of  a  block. 
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BUGS 

When  realloe  returns  0,  the  block  pointed  to  by  ptr  may  be  destroyed. 
AUoea  is  machine  dependent;  it’s  use  is  discouraged. 
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NAME 

mktemp  -  make  a  unique  file  name 

SYNOPSIS 

char  *mktemp(template) 
char  ^template} 

DESCRIPTION 

Mktemp  replaces  template  by  a  unique  file  name,  and  returns  the  address  of  the  template.  The 
template  should  look  like  a  file  name  with  six  trailing  X’s,  which  will  be  replaced  with  the  current 
process  id  and  a  unique  letter. 

Notei; 

•  Mktemp  actually  ekanget  the  template  string  which  you  pass,  this  means  that  you  cannot  use 
the  same  template  string  more  than  once  —  you  need  a  fresh  template  for  every  unique  file  you 
want  to  open. 

•  When  mktemp  is  creating  a  new  unique  filename  it  checks  for  the  prior  existence  of  a  file  with 
that  name.  This  means  that  if  you  are  creating  more  than  one  unique  filename,  it  is  bad  prac¬ 
tice  to  use  the  same  root  template  for  multiple  invocations  of  mktemp, 

SEE.  ALSO 

getpid(2) 
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NAME 

monitor,  monstartup,  moncontrol  -  prepare  execution  profile 
SYNOPSIS 

monttor(Iowpe,  highpe,  buffer,  bufsise,  nfbnc) 

Int  (*lowpe)0,  (•hlghpcX); 
short  bufferQi 

monttartup(Iowpe,  highpe) 
int  (*lowpe)0>  (*h!ghpc)()f 

moneontrol(mode) 

DESCRIPTION 

There  are  two  different  forms  of  monitoring  available:  An  executable  program  created  by: 
ce  -p  . .  . 

automatically  includes  calls  for  the  prof{l)  monitor  and  includes  an  initial  call  to  its  start-up  rou¬ 
tine  monttartup  with  default  parameters;  monitor  need  not  be  called  explicitly  except  to  gain  fine 
control  over  profit  buffer  allocation.  An  executable  program  created  by: 

•  cc  -pf  . . . 

automatically  includes  calls  for  the  gprof[l)  monitor. 

Momtartup  is  a  high  level  interface  to  profil\^).  Lowpe  and  highpe  specify  the  address  range  that 
is  to  be  sampled;  the  lowest  address  sampled  is  tiiat  of  lowpe  and  the  highest  is  just  below  highpe. 
Monttartup  allocates  space  using  siri;(2)  and  passes  it  to  monitor  (see  below)  to  record  a  histo* 
gram  of  periodically  sampled  values  of  the  program  counter,  and  of  counts  of  calls  of  certain  func¬ 
tions,  in  the  buffer.  Only  calls  of  functions  compiled  with  the  profiling  option  -p  of  ec(l)  are 
recorded. 

To  profile  the  entire  program,  it  b  sufficient  to  use 
extern  etext(); 

mon8tartup((]X8000,  etext); 

Etezt  lies  just  above  all  the  program  text,  see  eni(3). 

To  stop  execution  monitoring  and  write  the  results  on  the  file  mon.out,  use 
monitor(O); 

then  proJ{\)  can  be  used  to  examine  the  results. 

MoneoniTol  is  used  to  selectively  control  profiling  within  a  program.  This  works  with  either 
pre/(i)  or  gproJ{\)  type  profiling.  When  the  program  starts,  profiling  begins.  To  stop  the  collec¬ 
tion  of  histogram  ticks  and  call  counts  use  mnncnnlrnl(O);  to  resume  the  collection  of  histogram 
ticks  and  call  counts  use  moneontrot{l).  This  allows  the  cost  of  particular  operations  to  be  meas¬ 
ured.  Note  that  an  output  file  will  be  produced  upon  program  exit  irregardless  of  the  state  of 
moneontrol. 

Monitor  is  a  low  level  interface  to  profil{2).  Lowpe  and  highpe  are  the  addresses  of  two  functions; 
buffer  is  tke  address  of  a  (user  supplied)  array  of  hufsiee  short  integers.  At  most  nfune  call  counts 
can  be  kept.  For  the  results  to  be  significant,  especially  where  there  are  small,  heavily  used  rou¬ 
tines,  it  is  suggested  that  the  buffer  be  no  ntore  than  a  few  times  smaller  than  the  range  of  loca¬ 
tions  sampled.  Monitor  divides  the  buffer  into  space  to  record  the  histogram  of  program  counter 
samples  over  the  range  lowpe  to  highpe,  and  space  to  record  call  counts  of  functions  compiled  with 
the  -p  option  to  ee(l)-. 

To  profile  the  entire  program,  it  is  suffieieni  to  use 
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SUBROUTINES 


MONITOR  (3) 


extern  etext(); 

monitor(0x8000,  etext,  buf,  bufsixe,  nfunc); 

FILES 

mon.ottt 
SEE  ALSO 

cc(l),  prof(l),  gprof(l),  profiI(2),  sbrk(2) 
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NLIST(3) 


Q 


NAME 

nlist  -  get  entries  from  name  list 

SYNOPSIS 

#includo  <nliat«h> 

nliBt(filenAme|  nl) 
char  ^fllenamei 
struct  nlist  nl[]| 

DESCRIPTION 

Nli$i  examines  the  name  list  in  the  given  executable  output  file  and  selectively  extracts  a  list  of 
values.  The  name  list  consists  of  an  arrs^  of  structures  containing  names^  types  and  values.  The 
list  is  terminated  with  a  null  name.  Ed^h  name  is  looked  up  in  the  name  list  of  the  file.  If  the 
name  is  found,  the  type  and  value  of  the  name  are  inserted  in  the  next  two  fields.  If  the  name  is 
not  found,  both  entries  are  set  to  0.  See  u.oui(5)  for  the  structure  declaration. 

This  subroutine  is  useful  for  examining  the  ^stem  name  list  kept  in  the  file  /vmunlx.  In  this 
way  programs  can  obtain  system  addresses  that  are  up  to  date. 

SEE  ALSO 

a.out(5) 

DIAGNOSTICS 

All  type  entries  are  set  to  0  if  the  file  cannot  be  found  or  if  it  is  not  a  valid  namelist. 


o 
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NAME 

perror,  sysjerrlist,  8ys_nerr,  errno  -  system  error  messages 

SYNOPSIS 

perror(s) 
char  *■! 

Int  sys_nerr| 
char  *syajerrlist[]| 

lot  errnoi 
DESCRIPTION 

Perror  produces  a  short  error  message  on  the  standard  error  file  describing  the  last  error  encoun* 
tered  during  a  call  to  the  system  from  a  C  program.  First  the  argument  string  » is  printed,  then 
a  colon,  then  the  message  and  a  new-line.  Most  usefuUy,  the  argument  string  is  the  name  of  the 
program  which  incurred  the  error.  The  error  number  is  taken  from  the  external  variable  ermo 
(see  tn(ro(2)),  which  is  set  when  errors  occur  but  not  cleared  when  non-erroneous  calls  are  made. 

To  simplify  variant  formatting  of  messages,  the  vector  of  message  strings  eytjerrlitt  is  provided; 
errno  can  be  used  as  an  index  in  this  table  to  get  the  message  string  without  the  newline. 
Syajnerr  is  the  number  of  messages  provided  for  in  the  table;  it  should  be  checked  because  new 
error  codes  may  be  added  to  the  system  before  they  are  added  to  the  table. 

SEE  ALSO 

intro(2),  psignal(3) 
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NAME 

psignal,  sys^siglist  -  system  signal  messages 

SYNOPSIS 

p8!gnal(sis9  s) 
unsigned  sig| 
char 

char  ^sysjilgUstl]} 

DESCRIPTION 

Psignat  produces  a  short  message  on  the  standard  error  file  describing  the  indicated  signal.  First 
the  argument  string  9  is  printed,  then  a  colon,  then  the  name  of  the  signal  and  a  new^'line.  Most 
usefully,  the  argument  string  is  the  name  of  the  program  which  incurred  the  signal.  The  signal 
number  should  be  from  among  those  found  in  <,9ignaih>. 

To  simplify  variant  formatting  of  signal  names,  the  vector  of  message  strings  eye^sigliBi  is  pro¬ 
vided;  the  signal  number  can  be  used  as  an  index  in  this  table  to  get  the  signal  name  without  the 
newline.  The  define  NSIG  defined  in  <8ignaLk>  is  the  number  of  messages  provided  for  in  the 
table;  it  should  be  checked  because  new  signals  may  be  added  to  the  system  before  they  are  added 
to  the  table* 

SEE  ALSO 

perror(3),  8ignal(3) 
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QSORT(3) 


NAME 

qsort  -  quicker  sort 
SYNOPSIS 

qsort(base,  nel,  width,  eompar) 
char  *base; 

Int  (*eompar)()} 

DESCRIPTION 

Qtort  is  an  implementation  of  the  quicker-sort  algorithm.  The  first  argument  is  a  pointer  to  the 
base  of  the  data;  the  second  is  the  number  of  elements;  the  third  is  the  width  of  an  element  in 
bytes;  the  last  is  the  name  of  the  comparison  routine  to  be  called  with  two  arguments  which  are 
pointers  to  the  elements  being  compared.  The  routine  must  return  an  integer  less  than,  equal  to, 
or  greater  than  0  according  as  the  first  argument  is  to  be  considered  less  than,  equal  to,  or  greater 
than  the  second. 

SEE  ALSO 

sort(l) 
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RANDOM(3)  SUBROUTINES  RANDOM  (3) 


NAME 

random,  srandom,  initstate,  setstate  -  better  random  number  generator;  routines  for  changing 
generators 

SYNOPSIS 

long  randomO 

srandom(seed) 
tnt  seed) 

long  *lnlt8tate(aeed»  statoi  n) 
unsigned  seed| 
long  *state} 

Int  n| 

long  *setstate(Btate) 
long  *Btatet 

DESCRIPTION 

Random  uses  a  non-linear  additive  feedback  random  number  generator  employing  a  default  table 
of  size  31  long  integers  to  return  successive  pseudo-random  numbers  in  the  from  0  to  2  -1. 
The  period  of  this  random  number  generator  is  very  large,  approximately  16*(2  -1). 

Random! or andem  have  (almost)  the  same  calling  sequence  and  initialization  properties  as 
randjorand.  The  difference  is  that  rand(3C)  produces  a  much  less  random  sequence  -  in  fact,  the 
low  dozen  bits  generated  by  rand  go  through  a  cyclic  pattern.  All  the  bits  generated  by  random 
are  usable.  For  example,  "raudom()&01”  will  produce  a  random  binary  value. 

Unlike  orand,  orandorn  does  not  return  the  old  seed;  the  reason  for  this  is  that  the  amount  of  state 
information  used  is  much  more  than  a  single  word.  (Two  other  routines  are  provided  to  deal  with 
restarting/changing  random  number  generators).  Like  roni/(3C),  however,  random  will  by  default 
produce  a  sequence  of  numbers  that  can  be  duplicated  by  calling  orandorn  with  1  as  the  seed. 

The  initotate  routine  allows  a  state  array,  passed  in  as  an  argument,  to  be  initialized  for  future 
use.  The  size  of  the  state  array  (in  bytes)  is  used  by  initotate  to  decide  how  sophisticated  a  ran¬ 
dom  number  generator  it  should  use  —  the  more  state,  the  better  the  random  numbers  will  be. 
(Current  "optimal”  values  for  the  amount  of  state  information  are  8,  32,  64,  128,  and  256  bytes; 
other  amounts  will  be  rounded  down  to  the  nearest  known  amount.  Using  less  than  8  bytes  will 
cause  an  error).  The  seed  for  the  initialization  (which  specifies  a  starting  point  for  the  random 
number  sequence,  and  provides  for  restarting  at  the  same  point)  is  also  an  argument.  Initotate 
returns  a  pointer  to  the  previous  state  information  array. 

Once  a  statfi  has  been  initialized,  tke  oetotate  routine  t>rovides  for  rapid  switching  between  states. 
Setotate  returns  a  pointer  to  the  previous  state  arraqr;  its  argument  state  array  is  used  for  further 
random  number  generation  until  the  n<^xt  call  to  initotate  or  oetotate. 

Once  a  state  array  has  been  initializ^ti;  may  be  restarted  at  a  different  point  either  by  calling 
tnifs<«fe,(with  the  desired  seed,  the  state  array,  and  its  size)  or  by  calling  both  oetotate  (with  the 
state  arr^y)  and  orafidom  (with  the  desired  seed).  The  advantage  of  calling  both  oetotate  and 
orandorn  is  that  the  size  of  the  state  array  does  not  have  to  be  remembered  after  it  is  initialized. 

With  2M  bytes  of  sw-hjill^ormation,  the  period  of  the  random  number  generator  is  greater  than 
2^,  whicl  should  be  bumtlwiit  for  most  purposes. 

blAONOSTIOS 

tf  fnitotate  is  called  with  less  than  8  bytes  of  state  information,  or  if  oetotate  detects  that  the  state 
information  has  been  garbled,  error  messages  are  printed  on  the  standard  error  output. 

SEE  ALSO 

rand(3C) 
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BUGS 

About  2/3  the  speed  of  rand(3C}. 
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NAME 

r«_comp,  re_«xee  -  regular  expression  handler 

SYNOPSIS 

char  *rejeoinp(s) 
char 

r«_exee(s) 

char 

DESCRIPTION 

Rt^eomp  compiles  a  string  into  an  internal  form  suitable  for  pattern  matching.  Re_exec  checks 
the  argument  string  against  the  last  string  passed  to  re_comp. 

Re^eomp  returns  0  if  the  string  »  was  compiled  successfully;  otherwise  a  string  containing  an  error 
message  is  returned.  If  rc_comp  is  passed  0  or  a  null  string,  it  returns  without  changing  the 
currently  compiled  regular  expression. 

Rtjtxee  returns  1  if  the  string  «  matches  the  last  compiled  regular  expression,  0  if  the  string  $ 
failed  to  match  the  last  compiled  regular  expression,  and  -1  if  the  compiled  regular  expression  was 
invalid  (indicating  an  internsd  error). 

The  strings  passed  to  both  re_comp  and  rt_ezee  may  have  trailing  or  embedded  newline  charac¬ 
ters;  they  are  terminated  by  nulls.  The  regular  expressions  recognized  are  described  in  the 
manual  entry  for  ed(l),  given  the  above  difference. 

SEE  ALSO 

ed(l),  ex(l),  egrep(l),  fgrep(l),  grep(l) 

DIAGNOSTICS 

Rtjtxte  returns  -1  for  an  internal  error, 

Rt_j:omp  returns  one  of  the  following  strings  if  an  error  occurs: 

No  previous  regular  expression 
Regular  expreeeion  too  long 
unmatched  \( 
miesing  } 

too  manp \(\)  paire 
unmatched  \) 
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SCANDIR(3) 


NAME 

scandir,  alphasort  -  scan  a  directory 
SYNOPSIS 

#inelude  <aya/types.h> 

#lnelude  <sys/d!r.h> 

8caiidlr(dlriiamet  nameUat,  ■elceit  compar) 

char  *dlrnamet 

struct  direct  *(*namellstl])i 

Int  (*select)0l 

tut  (*eoinpar)()} 

alphasort(dl,  dS) 
struct  direct  **dl,  **d>| 

DESCRIPTION 

Seandir  reads  the  directory  dirname  and  builds  an  array  of  pointers  to  directory  entries  using  mat- 
loc{3).  The  third  parameter  is  a  pointer  to  a  routine  which  is  called  with  a  pointer  to  a  directory 
entry  and  should  return  a  non  zero  value  if  the  directory  entry  should  be  included  in  the  array.  If 
this  pointer  is  null,  then  all  the  directory  entries  will  be  included.  The  last  argument  is  a  pointer 
to  a  routine  which  is  passed  to  qtort{Z)  to  sort  the  completed  array.  If  this  pointer  is  null,  the 
array  is  not  sorted.  Atpkatort  is  a  routine  which  will  sort  the  array  alphabetically. 

Seandir  returns  the  number  of  entries  in  the  array  and  a  pointer  to  the  array  through  the  parame¬ 
ter  namelist. 

SEE  ALSO 

directory(3),  malloc(3),  q8ort(3) 

DIAGNOSTICS 

Returns  -1  if  the  directory  cannot  be  opened  for  reading  or  if  maUoe{Z)  cannot  allocate  enough 
memory  to  hold  all  the  data  structures. 
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NAME 

setjmp,  loogjmp  -  non-local  goto 
SYNOPSIS 

#lnetude  <MtiJnip.h> 

val  ss  te^mp(env) 

JmpJbuf  env} 

IongJmp(eiiv,  val) 

JmpJbuf  env; 

val  a*  j»etjmp(etiv) 

JmpJbuf  env; 

JlongJmp(enV)  val) 

Jmp_buf  env; 

DESCRIPTION 

Setjmp  and  lonsjmp  are  useful  for  dealing  with  errors  and  interrupts  encountered  in  a  low-level 
subroutine  of  a  progranli 

Setjmp  saves  its  stack  environment  in  env  for  later  use  by  longjtAp.  Setjmp  also  saves  the  register 
environment.  Setjmp  returns  the  value  0.  If  a  tongjmp  call  will  be  made,  the  routine  which  called 
eetjmp  should  not  return  until  after  the  tongjmp  has  returned  control  (see  below). 

Longjmp  restores  the  environment  saved  by  the  last  call  of  setjmp,  and  then  returns  in  such  a 
way  that  execution  continues  as  if  the  call  of  eetjmp  had  just  returned  the  value  val  to  the  func¬ 
tion  that  invoked  setjmp.  The  calling  function  must  not  itself  have  returned  in  the  interim,  oth¬ 
erwise  longjmp  will  be  returning  control  to  a  possibly  non-existent  environment.  All  memory- 
bound  data  have  values  as  of  the  time  tongjmp  was  called.  The  machine  registers  are  restored  to 
the  values  they  had  at  the  time  that  eetjmp  was  called.  But,  because  the  register  storage  class  is 
only  a  hint  to  the  C  compiler,  variables  declared  as  register  variables  may  not  necessarily  be 
assigned  to  machine  registers,  so  their  values  are  unpredictable  after  a  longjmp.  This  is  especially 
a  problem  for  programmers  trying  to  write  machine-independent  C  routines. 

The  following  code  fragment  indicates  the  flow  of  control  of  the  eetjmp  nad  fong;mp  combination: 

. .  .  /unction  deelaration 

JmpJbuf  my_environment; 

. . .  code  .  . . 

If  (setjmp  ( myjenvironment  )^)  { 

thie  ie  the  code  o/ter  the  return  from  longjmp 
. .  .  more  code . 

register  variables  have  unpredictable  values 
.  ,  .  more  code  .... 

}  else  {. 

thie  is  the  return  firom  eetjmp 
. . .  more  code  .... 

Do  not  modify  register  variables 
in  thie  teg  of  the  code 
. . .  more  code  .... 

} 

Setjmp  2uid  ionpjmp  save  and  restore  the  signal  mask  »ig8etma9k{2)t  while  jBctjmp  ^longjmp 
manipulate  only  the  C  stack  and  registers. 
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SEE  ALSO 

8igsetmask(2),  8igvec(2),  signals) 

BUGS 

Seijmp  does  not  save  current  notion  of  whether  the  process  is  executing  on  the  signal  stack.  The 
result  is  that  a  longjmp  to  some  place  on  the  signal  stack  leaves  the  signal  stack  state  incorrect. 
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NAME 

setuid,  seteuid,  setruid,  setgid,  setegid,  setrgid  -  set  user  and  group  ID 

SYNOPSIS 

Betuld(uld) 

seteuld(eutd) 

•etruld(ruid) 

setgld(gld) 

setegid(e^d) 

Mtrgld(rgld) 

DESCRIPTION 

Setuid  {eetgid)  sets  both  the  real  and  effective  user  ID  (group  ID)  of  the  current  process  to  as 
specified. 

Seteuid  {eetegid)  sets  the  effective  user  ID  (group  ID)  of  the  current  process. 

Setruid  (eetruid)  sets  the  real  user  ID  (group  ID)  of  the  current  process. 

These  calls  are  only  permitted  to  the  super^user  or  if  the  argument  is  the  real  or  effective  ID. 

SEE  ALSO 

setreuid(2),  8etregid(2),  getuid(2),  getgid(2) 

DIAGNOSTICS 

Zero  is  returned  if  the  user  (group)  ID  is  set;  -1  is  returned  otherwise,  with  the  global  variable 
errno  set  as  for  setreuid  or  setregid. 
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NAME 

signal  -  simplified  software  signal  facilities 
SYNOPSIS 

#lnelude  <s!gnal«h> 

('''slgnal(sig,  fune))() 
void  (*fune)0l 

DESCRIPTION 

Signal  is  a  simplified  interface  to  the  more  general  ngvcc{2)  facility. 

A  signal  is  generated  by  some  abnormal  event,  initiated  by  a  user  at  a  terminal  (quit,  interrupt, 
stop),  by  a  program  error  (bus  error,  etc.),  by  request  of  another  program  (kUl),  or  when  a  process 
is  stopped  because  it  wishes  to  access  its  control  terminal  while  in  the  background  (see  t<y(4)). 
Signals  are  optionally  generated  when  a  process  resumes  after  being  stopped,  when  the  status  of 
child  processes  changes,  or  when  input  is  ready  at  the  control  terminal.  Most  signals  cause  termi* 
nation  of  the  receiving  process  if  no  action  is  taken;  some  signals  instead  cause  the  process  receiv* 
ing  them  to  be  stopped,  or  are  simply  discarded  if  the  process  has  not  requested  otherwise. 
Except  for  the  SIGKILL  and  SIGSTOP  signals,  the  signal  call  allows  signals  either  to  be  ignored 
or  to  cause  an  interrupt  to  a  specified  location.  The  following  is  a  list  of  all  signals  with  names  as 
in  the  include  file  <»ignal.h>: 


SIGHUP 

1 

hangup 

SIGINT 

2 

interrupt 

SIGQUIT 

3* 

quit 

SIGILL 

4* 

illegal  instruction 

SIGTRAP 

5* 

trace  trap 

SIGIOT 

6* 

lOT  instruction 

SIGEMT 

7* 

EMT  instruction 

SIGFPE 

8* 

fioating  point  exception 

SIGKILL 

9 

kill  (cannot  be  caught  or  ignored) 

SIGBUS 

10* 

bus  error 

SIGSEGV 

11* 

segmentation  violation 

SIGSYS 

12* 

bad  argument  to  system  call 

SIGPIPE 

13 

write  on  a  pipe  with  no  one  to  read  it 

SIGALRM 

14 

alarm  clock 

SIGTERM 

15 

software  termination  signal 

SIGURG 

16 

urgent  condition  present  on  socket 

SIGSTOP 

17t 

stop  (cannot  be  caught  or  ignored) 

SIGTSTP 

18t 

stop  signal  genera.ted  from  keyboard 

SIGCONT 

lOh 

continue  after  stop 

SIGCHLD 

20e 

child  status  has  changed 

SIGTTIN 

21t 

background  read  attempted  frmn  control  terminal 

SIGTTOU 

22t 

background  write  attempted  to  control  terminal 

SIGIO  1 

23 

i/o  b  possible  on  a  descriptor  (see  fcntl{2)) 

SIGXCPb 

24 

cpu  time  limit  exceeded  (see  eetrtimit{2)) 

SIGXFS2 

25 

file  size  limit  exceeded  (see  tetflimit{2)) 

SIGVTALRM  26 

virtual  time  alarm  (see  8eiitimer{2)) 

SIGPROF 

27 

profiling  timer  alarm  (see  $etititner{2)) 

SIGWINCH 

28 

window  changed 

The  starred  siguab  in  the  Ibt  above  cause  a  core  image  if  not  caught  or  ignored. 

If /unc  is  SIGJJFL,  the  default  action  for  signal  eig  is  reinstated;  this  default  is  termination  (with 
a  core  image  for  starred  signab)  except  for  signals  marked  with  •  or  f.  Signals  marked  with  e  are 
dbcarded  if  the  action  b  SIG_DFL;  signab  marked  with  t  cause  the  process  to  stop.  If  func  is 
SIG_rGN  the  signal  is  subsequently  ignored  and  pending  instances  of  the  signal  are  dbcarded. 


52 


Last  change:  IS  June  1983 


Sun  Release  1.1 


SIGNAL  (3) 


SUBROUTINES 


SIGNAL  (3) 


Otherwise,  when  the  signal  occurs  further  occurences  of  the  signal  are  automatically  blocked  and 
June  Is  called. 

A  return  from  the  function  unblocks  the  handled  signal  and  continues  the  process  at  the  point  it 
was  interrupted.  Unlike  previous  slgnsJ  feclUtlest  the  handler  June  remidns  Installed  after 
a  slgnid  him  been  delivered. 

If  a  caught  signal  occurs  during  certain  system  calls,  causing  the  call  to  terminate  prematurely, 
the  call  is  automatically  restarted.  In  particular  this  can  occur  during  a  read  or  wrile{2)  on  a  slow 
device  (such  as  a  terminal;  but  not  a  file)  and  during  a  wait(2). 

The  value  of  eignei  is  the  previous  (or  initial)  value  of  June  for  the  particular  signal. 

After  a  Jork{2)  or  uJork(2)  the  child  inherits  all  signals.  An  ezeeve(2)  resets  all  caught  signals  to 
the  default  action;  ignored  signals  remain  ignored. 

RETURN  VALUE 

The  previous  action  is  returned  on  a  successful  call.  Otherwise,  -1  is  returned  and  errno  is  set  to 
indicate  the  error. 

ERRORS 

Signal  will  fail  and  no  action  will  take  place  if  one  of  the  following  occur: 

[EINVAL]  Sig  is  not  a  valid  signal  number. 

[EINVAL]  An  attempt  is  made  to  ignore  or  supply  a  handler  for  SIGKILL  or  SIGSTOP. 
[EINVAL]  An  attempt  is  made  to  ignore  SIGCONT  (by  default  SIGCONT  is  ignored). 

SEE  ALSO 

kill(l),  ptraee(2),  kill(2),  8igvec(2),  sigblock(2),  8lgsetma8k(2),  8igpau8e(2),  8ig8tack(2),  8etjmp(3), 
tty(4) 

NOTES  (VAX-11) 

The  handler  routine  can  be  declared: 

haBdler(8ig,  code,  sep) 

Here  tig  is  the  signal  number,  into  which  the  hardware  faults  and  traps  are  mapped  as  defined 
below.  Code  is  a  parameter  which  is  either  a  constant  as  given  below  or,  for  compatibility  mode 
faults,  the  code  provided  by  the  hardware.  Sep  is  a  pointer  to  the  struct  sigeontext  used  hy  the 
system  to  restore  the  process  context  from  before  the  signal.  Compatibility  mode  faults  are  dis¬ 
tinguished  from  the  other  SIGILL  traps  by  having  PSLjCM  set  in  the  psl. 

The  following  defines  the  mapping  of  hardware  traps  to  signals  and  codes.  All  of  these  symbols 
are  defined  in  <tignat.h>i 


Hardware  condition 

Signal 

Code 

Arithmetic  traps: 

Integer  overflow 

SIGFPE 

FPE_INTOVF_TRAP 

Integer  division  by  zero 

SIGFPE 

FPE_INTDIV_TRAP 

Floating  overflow  trap 

SIGFPE 

FPE_FLTOVF_TRAP 

Floating/decimal  division  by  zero 

SIGFPE 

FPE_FLTDIV_TRAP 

Floating  underflow  trap 

SIGFPE 

FPE_FLTUND_TRAP 

Decimal  overflow  trap 

SIGFPE 

FPE_DECOVF_TRAP 

Subscript-range 

SIGFPE 

FPE_SUBRNG_TRAP 

Floating  overflow  fault 

SIGFPE 

FPE_FLTOVF_FAULT 

Floating  divide  by  zero  fault 

SIGFPE 

FPE_FLTDnLFAULT 

Floating  underflow  fault 

Length  access  control 

Protection  violation 

SIGFPE 

SIGSEGV 

SIGBUS 

FPE_FLTUND_FAULT 

Reserved  instruction 

SIGILL 

ILL_RESAD_FAULT 
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Customer-reserved  instr. 

SIGEMT 

c 

Reserved  operand 

SIGILL  ILLJPRIVIN_FAULT 

Reserved  addressing 

SIGILL  ILL_RESOP_FAULT 

Trace  pending 

SIGTRAP 

Bpt  instruction 

SIGTRAP 

Compatibility-mode 

SIGILL  hardware  supplied  code 

Chme 

SIGSEGV 

Chms 

SIGSEGV 

Cbmu 

SIGSEGV 

o 
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SLEEP (3) 


NAME 

sleep  -  suspend  execution  for  interval 

SYNOPSIS 

slMp(sMon<is) 
unsigned  seeondei 

DESCRIPTION 

Sleep  suspends  the  current  process  from  execution  for  the  number  of  seconds  specified  by  the 
argument.  The  actual  suspension  time  may  be  up  to  1  second  less  than  that  requested,  because 
scheduled  wakeups  occur  at  fixed  l«second  intervals,  and  may  be  an  arbitrary  amount  longer 
because  of  other  activity  in  the  system. 

Steep  is  implemented  by  setting  an  interval  timer  and  pausing  until  it  expires.  The  previous  state 
of  this  timer  is  saved  and  restored.  If  the  sleep  time  exceeds  the  time  to  the  expiration  of  the 
previous  value  of  the  timer,  the  process  sleeps  only  until  the  timer  would  have  expired,  and  the 
signal  which  occurs  with  the  expiration  of  the  timer  is  sent  one  second  later. 

SEE  ALSO 

setitimer(2),  sigpause(2) 

BUGS 

An  interface  with  finer  resolution  is  needed. 
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STRING  (3) 


NAME 

strcat,  strncat,  strcmp,  strncmp,  etrcpy,  stracpy,  strlen,  index,  rindex  -  string  operations 
SYNOPSIS 

#Inelude  <strlngs.li> 

char  *atreat(al,  b2) 
char 

char  *atrneat(alt  n) 
char  *al|  *a2| 

atremp(al,  a2) 
char  *al,  *a2) 

atrncinp(al>  a2»  n) 
char  *al,  *'a2| 

char  *atrepy(al,  a2) 
char  *al,  '''a2| 

char  *atrnepy(al,  a2,  n) 
char  *al, 

atrleii(a) 
char  '*at 

char  *Index(a|  e) 
char  e| 

char  *rhidex(a«  e) 
char  *a,  c} 

DESCRIPTION 

These  functions  operate  on  null«terminated  strings.  They  do  not  check  for  overflow  of  any  receiv¬ 
ing  string. 

Streat  appends  a  copy  of  string  »e  to  the  end  of  string  si.  Strncat  copies  at  most  n  characters. 
Both  return  a  pointer  to  the  null-terminated  result. 

Strcmp  compares  its  arguments  and  returns  an  integer  greater  than,  equal  to,  or  less  than  0, 
according  as  si  is  lexicographically  greater  than,  equal  to.  or  less  than  »i.  Strnemp  makes  the 
same  comparison  but  looks  at  at  most  n  characters. 

Strepji  copies  string  »S  to  si,  stopping  after  the  null  character  has  been  moved.  Strnepy  copies 
exactly  n  characters,  truncating  or  null-padding  $t;  the  target  may  not  be  null-terminated  if  the 
length  of  s£  is  n  or  more.  Both  return  si. 

Strten  returns  the  number  of  non-null  characters  in  s. 

Index  (rtndex)  returns  a  pointer  to  the  flrst  (last)  occurrence  of  character  e  in  string  s,  or  sero  if  e 
does  not  occur  in  the  string. 

BUGS 

Strcmp  uses  native  character  comparison,  which  is  signed  on  the  Sun. 

On  the  Sun  processor  (and  on  some  other  machines),  you  can  NOT  use  a  sero  pointer  to  indicate 
a  null  string.  A  sero  pointer  is  an  error  and  results  in  an  abort  of  the  program.  If  you  wish  to 
indicate  a  null  string,  you  must  have  a  pointer  that  points  to  an  explicit  null  string.  On  PDP-ll’s 
and  VAX’en,  a  source  pointer  of  lero  (0)  can  generally  be  used  to  indicate  a  null  string.  Program¬ 
mers  using  NULL  to  represent  an  empty  string  should  be  aware  of  this  portability  issue. 
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NAME 

■wtb  -  bytet 
SYNOPSIS 

■w«b(froitt»  to,  nbytw) 
ehor  *froin,  *to| 

DESORiPTION 

Swab  copies  nbj/tea  bytes  pointed  to  by  from  to  the  position  pointed  to  by  to,  exchanging  adjacent 
even  and  odd  bytes.  It  is  useful  for  canying  binary  data  between  high-ender  machines  (IBM 
300’s,  MGOSOOO’s,  etc)  and  low-ender  machines  (PDP-ll’s  and  VAX’es). 

Myfes  should  be  even. 

The  from  and  to  addresses  should  not  overlap  in  portable  programs. 


Sun  Release  1.1 


Last  change:  20  March  1984 


57 


SYSL0G(3) 


SUBROUTINES 
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NAME 

syslog,  openlog,  closelog  -  control  system 
SYNOPSIS 

#lnelud«  <nyslog.h> 

openlog(ldent,  logstat) 
char  *ldent| 

■yBlog(prlorlty>  mMsagCt  paramatara  m  ) 
char  ’‘‘maBsagai 

ctoaalogO 

DESCRIPTION 

Sfftloff  arranges  to  write  the  message  onto  the  system  log  maintained  by  sys/eg(8).  The  message  is 
tagged  with  priority.  The  message  looks  like  a  prinf/(3S)  string  except  that  96m  is  replaced  by 
the  current  error  message  (collected  from  errno).  A  trailing  newline  is  added  if  needed.  This 
message  will  be  read  by  $ytlog{S)  and  output  to  the  system  console  or  files  as  appropriate. 

If  special  processing  is  needed,  openlog  cm  be  called  to  initialise  the  log  file.  Parameters  are  ident 
which  is  prepended  to  every  message,  and  logoM  which  is  a  bit  field  indicating  special  status; 
current  values  are: 

LOG_piD  log  the  process  id  with  each  message:  useful  for  identifying  instantiations  of  dae* 
mons. 

Openlog  returns  zero  on  success.  U  eyelog  cannot  send  datagrams  to  «y«fag(8),  then  it  writes  on 
/  devfeontole  instead.  If  Idevfeonoote  cannot  be  written,  standard  error  is  used.  In  either  ease,  it 
returns  •!. 

Clotelog  can  be  used  to  close  the  log  file.  It  is  automatically  closed  on  a  successful  exec  system 
call  (see  execvt(2)). 

EXAMPLES 

syslog(LOOj5ALE2RT,  "who:  internal  error  23’*); 
openlog(”serverftp”,  L0Q_PID); 

8y8log(LOG_|NFO,  "Connection  from  host  %d”,  CallingHost); 

SEE  ALSO 

8yslog(8) 
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NAME 

system  -  issue  a  shell  command 

SYNOPSIS 

ayatem(strlng) 
char  *strlng} 

DESCRIPTION 

System  causes  the  tiring  to  be  gives  to  «A(1)  as  input  as  if  the  string  had  been  typed  as  a  com* 
mand  at  a  terminal.  The  current  process  waits  until  the  shell  has  completed,  then  returns  the 
exit  status  of  the  shell. 

SEE  ALSO 

popen(3S),  execve(2),  wait(2) 

DIAGNOSTICS 

Exit  status  127  indicates  the  shell  couldn’t  be  executed. 
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NAME 

ttyname,  isatty,  ttyslot  -  find  name  of  a  terminal 
SYNOPSIS 

char  *ttynaine(flle<let) 
iBatty(flledM) 
ttyalotO 
DESCRIPTION 

Tlpname  returns  a  pointer  to  the  null-terminated  path  name  of  the  terminal  device  associated 
with  file  descriptor  fiedes. 

hatty  returns  1  if  is  associated  with  a  terminal  device,  0  otherwise. 

Ttytlot  returns  the  number  of  the  entry  in  the  ffys(5)  file  for  the  control  terminal  of  the  current 
process. 

FILES 

/dev/* 

/etc/ttys 

SEE  ALSO 

ioctl(2),  tty8(5) 

DIAGNOSTICS 

Ttyname  returns  a  null  pointer  (0)  if  filedet  does  not  describe  a  terminal  device  in  directory 
‘/dev’. 

Ttyelot  returns  0  if  ‘/etc/ttys’  is  inaccessible  or  if  it  cannot  determine  the  control  terminal. 

BUGS 

The  return  value  points  to  static  data  whose  content  is  overwritten  by  each  call. 
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NAME 

valloc  -  aligned  memoty  allocator 

SYNOPSIS 

char  *valloe(slM) 
unsigned  alsei 

DESCRIPTION 

Valloc  allocates  size  bytes  aligned  on  a  page  boundary.  It  is  implemented  by  calling  malloc{3) 
with  a  slightly  larger  request,  saving  the  true  beginning  of  the  block  allocated,  and  returning  a 
properly  aligned  pointer. 

DIAGNOSTICS 

Valtee  returns  a  null  pointer  (0)  if  there  is  no  available  memory  or  if  the  arena  has  been  detect* 
ably  corrupted  by  storing  outside  the  bounds  of  a  block. 

BUGS 

Vfree  isn’t  implemented. 
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VAR  ARCS  (3) 


SUBROUTINES 


VARARGS(3) 


NAME 

varargs  -  variable  argument  list 
SYNOPSIS 

#lnclud«  <vararga.h> 

/unc(ten(va_allst) 

va.del 

vajiat  pvar; 

vajitart(pv(ir); 

f  •“  va_apg(putfr,  type); 

va_end(pvar); 

DESCRIPTION 

This  set  of  macros  provides  a  means  of  writing  portable  procedures  that  accept  variable  argument 
lists.  Routines  having  variable  argument  lists  (such  as  prtni/(3S))  that  do  not  use  varargs  are 
inherently  nonportable,  since  different  machines  use  different  argument  passing  conventions. 

va_allBt  is  used  in  a  function  header  to  declare  a  Variable  argumeni  list. 

vajdel  is  a  declaration  for  vajallat.  Note  that  there  is  no  semicolon  after  va_deL 

vajlst  is  a  type  which  can  be  used  for  the  variable  pvar,  which  is  used  to  traverse  the  list.  One 
such  variable  must  always  be  declared. 

v«jitart(pvar)  is  called  to  initialize  pvar  to  the  beginning  of  the  list. 

va^arg(pvar,  type)  will  return  the  next  argument  in  the  list  pointed  to- by  pvar.  Type  is  the  type 
the  argument  is  expected  to  be.  Different  types  can  be  mbced,  but  it  is  up  to  the  routine  to  know 
what  type  of  argument  is  expected,  since  it  cannot  be  determined  at  runtime. 

vajend(pu«r)  is  used  to  finish  up^ 

MuU^rle  traversals^eacb  bracketed  by.va_ptart ...  vajendf  are  possible.. 

EXAMPLE 

#liielude  <var3rgs.h> 

execl(va..jtOM) 

vajdel 

( 

vaJSit  ap; 
ehan  *file; 
diaf^*afgi^tOf^;- 
Gai  argtto  «  Or 

ra^ta»e(j^>^. 

file«  ^MK:Jt*g(ap»  «ba»J^ 

vdaiB  (aagatatg^«H‘tf*  trajpag^i^clM* 

9 

va.emd(ap)r- 
retvrit  exe^ffls^avgn]^ 

BUGS 

It  is  to  the  caUittg  routine  to  detenome  hovnmai^argnBaeato  there  are,  since  ft  is  not  possible 
to  determine  this  ftou  the  stack  frame.  Par  exanqsle,  eneci  passes  a  0  to  signal  the  end  of  the 
list.  Brintf  can  tell  how  many  arguments  are  suppos^  tabe  t^eby  the  format. 
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NAME 

intro  -  introduction  to  compatibility  library  functions 
DESCRIPTION 

These  functions  constitute  the  compatibility  library  portion  of  libe.  They  are  automatically 
loaded  as  needed  by  the  C  compiler  ce(l).  The  link  editor  searches  this  library  under  the  “-Ic” 
option.  Use  of  these  routines  should,  for  the  most  part,  be  avoided.  Manual  entries  for  the  func¬ 
tions  in  this  library  describe  the  proper  routine  to  use. 

LIST  OP  FUNCTIONS 


Name 

Appears  on  Page  Description 

alarm 

alarm.3c 

schedule  signal  after  specified  time 

ftime 

time.3e 

get  date  and  time 

getopt 

getopt.3c 

get  option  tetter  from  argv 

gtty 

stty  .3c 

set  and  get  terminal  state 

nice 

nice.Sc 

set  program  priority 

optarg 

getopt.3e 

get  option  letter  from  argv 

optind 

getopt.3e 

get  option  letter  from  argv 

pause 

pause.Sc 

stop  until  signal 

rand 

rand  ,3c 

random  number  generator 

srand 

rand  .3c 

random  number  generator 

stty 

stty .3c 

set  and  get  terminal  state 

time 

time.3c 

get  date  and  time 

times 

times.3c 

get  process  times 

tmpnam 

tmpnam.3c 

create  a  name  for  a  temporary  file 

ulimit 

ulimit.3c 

get  and  set  user  limits 

utime 

utime.3e 

set  file  times 

vlimit 

viimit.3c 

control  maximum  system  resource  consumption 

vtimes 

vtimes.3c 

get  information  about  resource  utilization 
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ALARM(3C) 


NAME 

alarm  -  schedule  signal  after  specified  time 

SYNOPSIS 

aIarm(8eeond8) 
unsigned  aeeonds; 

DESCRIPTION 

This  Interfaee  b  obsoleted  by  8etitlmer(S). 

Alarm  causes  signal  SIGALRM,  see  siffvee{2),  to  be  sent  to  the  invoking  process  in  a  number  of 
seconds  given  by  the  argument.  Unless  caught  or  ignored,  the  signal  terminates  the  process. 

Alarm  requests  are  not  stacked;  successive  calls  reset  the  alarm  clock.  If  the  argument  is  0,  any 
alarm  request  is  canceled.  Because  of  scheduling  delays,  resumption  of  execution  of  when  the  sig> 
nal  is  caught  may  be  delayed  an  arbitrary  amount.  The  longest  specifiable  delay  time  is 
2147483647  seconds. 

The  return  value  is  the  amount  of  time  previously  remainbg  in  the  alarm  clock. 

SEE  ALSO 

sigpan8e(2),  8igvec(2),  signal(3),  sleep(3) 
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GETOPT{3C) 


NAME 

getopt,  optarg,  optind  -  get  option  letter  from  argv 
SYNOPSIS 

Int  getopt(arge,  avgv«  optatring) 

Int  argtf 
char  **argv| 
char  *opt8trIng| 

extern  char  ^optarg} 
extern  int  optind} 

DESCRIPTION 

Xhie  routine  Is  Included  for  compatibility  with  UNDC  system»in.  It  Is  of  marginal 
value«  and  should  not  be  used  In  new  programs. 

Getopt  returns  the  next  option  letter  in  argv  that  matches  a  letter  in  optatring.  Optatring  is  a 
string  of  recognized  option  letters;  if  a  letter  is  followed  by  a  colon,  the  option  is  expected  to  have 
an  argument  that  may  or  may  not  be  separated  from  it  by  white  space.  Optarg  is  set  to  point  to 
the  start  of  the  option  argument  on  return  from  gatopt. 

Getopt  places  in  optind  the  argv  index  of  the  next  argument  to  be  processed.  Because  optind  is 
external,  it  is  normally  initialized  to  zero  automatically  before  the  first  call  to  getopt. 

When  all  options  have  been  processed  (i.e.,  up  to  the  first  non^option  argument),  getopt  returns 
EOF.  The  special  option  —  may  be  used  to  delimit  the  end  of  the  options;  EOF  will  be  returned, 
and  —  will  be  skipped. 

DIAGNOSTICS 

Getopt  prints  an  error  message  on  sMerr  and  returns  a  question  mark  (?)  when  it  encounters  an 
qption  letter  not  included  in  optatring. 

EXAMPLE 

The  following  code  fragment  shows  how  one  might  process  the  arguments  for  a  command  that  can 
take  the  mutually  exclusive  options  a  and  bf  and  the  options  f  and  Oy  both  of  which  require  argu* 
ments: 

main(argc,  argv) 
int  arge; 
char  **argv; 

{ 

int  c; 

extern  int  optind; 
extern  char  *optar|K 


while  ((c  *=  getopt(argc,  argv,  ’’abf:©:*))  f*-  EOF) 
switch  (c)  { 
case  V: 

if  (bflg) 

errflg-f  + ; 
else 

aflg+  +  ; 

break; 

case  *b’; 

if  (aflg) 

errflg+  + ; 
else 


Sun  Release  1.1 


Last  change:  25  August  1983 


3 


GET0PT(3C) 


COMPATIBILITY  ROUTINES 


GETOPT(3C) 


bproc(); 

break; 

case  T: 

infile  optarg; 
break; 

case  'o’: 

ofile  B  optarg; 
bufsiza  B  612; 
break; 

case  'T': 

errflg+  + ; 

} 

if  (errflg)  { 

fprintf^stderr,  ’’usage: 
exit(2); 

} 

for  (;  optind  <  argc;  optind+  +  )  { 
if  (acceBs(argv(optiiLd],  4))  { 


) 
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NICE(3C) 


NAME 

nic«  -  set  program  priority 

SYNOPSIS 

niee(Iner) 

DESCRIPTION 

Thb  Interfae*  Is  obsoleted  by  aetprtorlty(2). 

The  scheduling  priority  of  the  process  is  augmented  by  tncr.  Positive  priorities  get  less  service 
than  normal.  Priority  10  is  recommended  to  users  who  wish  to  execute  long-running  programs 
without  flak  from  the  administration. 

Negative  increments  are  ignored  except  on  behalf  of  the  super-user.  The  priority  is  limited  to  the 
range  -20  (most  urgent)  to  20  (least). 

The  priority  of  a  process  is  passed  to  a  child  process  by  fork{2).  For  a  privileged  process  to  return 
to  normal  priority  from  an  unknown  state,  nice  should  be  called  successively  with  arguments  -40 
(goes  to  priority  -20  because  of  truncation),  20  (to  get  to  0),  then  0  (to  maintain  compatibility 
with  previous  versions  of  this  call). 

SEE  ALSO 

nice(l),  getpriority(2),  8etpriority(2),  fork(2),  renice(8) 
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PAUSE(3C) 


NAME 

pause  -  stop  until  signal 

SYNOPSIS 

pause() 

DESCRIPTION 

Thif  function  Is  obsoleted  by  sigpause(S). 

Pau9t  never  returns  normally.  It  is  used  to  give  up  control  while  waiting  for  a  signal  from  kiU{2) 
or  an  interval  timer,  see  eetiHmer{2).  Upon  termination  of  a  signal  handler  started  during  a 
pause,  the  pause  call  will  return. 

RETURN  VALUE 

Always  returns  -1. 

ERRORS 

Pause  always  returns: 

[EINTR]  The  call  was  interrupted. 

SEE  ALSO 

kin(2),  select(2),  8igpau8e(2) 
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RAND(3C) 


COMPATBILITY  ROUTINES 


RAND(3C) 


NAME 

rand,  srand  -  random  number  generator 

SYNOPSIS 

•rand(aced) 

Int  needi 

rand() 

DESCRIPTION 

The  newer  random(3)  should  be  used  In  new  applications!  rand  remains  for  eompatl- 
bilty. 

Rand  uses  a  multiplicative  congruential  random  number  generator  with  period  2*^  to  return  suc¬ 
cessive  pseudo-random  numbers  in  the  range  from  0  to 

The  generator  is  reinitialized  by  calling  trand  with  1  as  argument.  It  can  be  set  to  a  random 
starting  point  by  calling  trand  with  whatever  you  like  as  argument. 

SEE  ALSO 

random(3) 

BUGS 

The  low  bits  of  the  numbers  generated  are  not  very  random;  use  the  middle  bits.  In  particular 
the  lowest  bit  is  deterministically  altematingly  0  and  1. 
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STTY(3C) 


COMPATIBILITY  ROUTINES 


STTY(3C) 


NAME 

Btty,  gtty  -  set  and  get  terminal  state 

SYNOPSIS 

#litelu<le  <agttyth> 

stty(fd|  buf) 

Ini  fd| 

struct  agttyb  *buf| 

gtty(fd,  buf) 

Int  fd{ 

struct  sgttyb  *buf{ 

DESCRIPTION 

This  Interface  Is  obsoleted  by  Ioctl(S). 

Stty  sets  the  state  of  the  terminal  associated  with  fd.  Gtty  retrieves  the  state  of  the  terminal  asso¬ 
ciated  with  fd.  To  set  the  state  of  a  terminal  the  call  must  have  write  permission. 

The  call  is  actually  “ioctl(fd,  TIOCSETP,  buf)”,  while  the  ytty  caU  is  ‘‘ioctl(fd,  TIOCGETP, 
buf)”.  See  ioctt{2)  and  f<v(4)  for  an  explanation. 

DIAGNOSTICS 

If  the  call  is  successful  0  is  returned,  otherwise  -1  is  returned  and  the  global  variable  errno  con¬ 
tains  the  reason  for  the  failure. 

SEE  ALSO 

ioctl(2),  tty(4) 
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TIME(SG) 


COMPATIBILITY  ROUTINES 


TIME(3C) 


NAME 

time,  ftime  -  get  d»te  and  time 
SYNOPSIS 

tlmeofday  a  tlme(0) 

tlmeofday  a  tIme(tloe) 
long  Hloc} 

^include  <eye/types.h> 

#Inelude  <aye/tlin«b.h> 
ftline(tp) 

•truet  tlmeb  *tp} 

DESCRIPTION 

Theee  Interface*  are  obioleted  by  gettlmeofday(2). 

Time  returns  the  time  since  00:00:00  GMT,  Jan.  1,  1070,  measured  in  seconds. 

If  the  is  nonnull,  the  return  value  is  also  stored  in  the  place  to  which  the  points. 

The  ftime  entry  fills  in  a  structure  pointed  to  by  its  argument,  as  defined  by  <eyeftimeh.h>\ 

struct  timeb 

{ 

timejt  time; 
unsigned  short  miiiitm; 
short  timezone; 
short  dstflag; 

}5 

The  structure  contains  the  time  since  the  epoch  in  seconds,  up  to  1000  milliseconds  of  more- 
precise  interval,  the  local  time  zone  (measured  in  minutes  of  time  westward  from  Greenwich),  and 
a  fiag  that,  if  nonzero,  indicates  that  Daylight  Saving  time  applies  locally  during  the  impropriate 
part  of  the  year. 

SEE  ALSO 

date(l),  gettimeofday(2),  settimeofday(2),  ctime(3) 
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TIMES  (3C) 


COMPATIBILITY  ROUTINES 


TIMES  (3C) 


NAME 

times  -  get  process  times 


SYNOPSIS 

#inelude  <By8/types.h> 
#lnelude  <sys/tlmef*h> 

tlines(buffer) 
struct  tms  ^buffer) 


DESCRIPTION 

This  interface  Is  obsoleted  by  getrttsage(S)* 


Timet  returns  time-accounting  information  for  the  current  process  and  for  the  terminated  child 
processes  of  the  current  process.  All  times  are  in  I/HZ  seconds,  where  HZ  is  60. 

This  is  the  structure  returned  by  timet: 


struct  tms  { 

time_t  tms_utime; 
time^t  tms_^time; 
timejt  tmsjcutime; 
time_t  tms^cstime; 

); 


/*  user  time  •/ 

/•  system  time  •/ 

/*  user  time,  children  */ 

/•  system  time,  children  */ 


The  children  times  are  the  sum  of  the  children's  process  times  and  their  children’s  times. 
SEE  ALSO 

time(l),  getrusage(2),  wait3(2),  time(3C) 


c 
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COMPATIBILITY  ROUTINES 


TMPNAM(3C) 


NAME 

tmpnam  -  create  a  name  for  a  temporary  file 

SYNOPSIS 

#lnelttd«  <atdlo.h> 

char  *tmpnain(a) 
char  *•! 

DESCRIPTION 

Thla  routine  Is  Included  for  ayetemrlll  eompatlbiUty* 

Tmpnam  generates  a  file  name  that  can  safely  be  used  for  a  temprary  file.  If  (int)s  is  zero, 
tmpnam  leaves  its  result  in  an  internal  static  area  and  returns  a  pointer  to  that  area.  The  next 
call  to  tmpnam  will  destroy  the  contents  of  the  area.  If  (int)s  is  nonzero,  s  is  assumed  to  be  the 
address  of  an  array  of  at  least  Ljtmpnnm  bytes;  tmpnam  places  its  result  in  that  array  and 
returns  $  as  its  value. 

Tmpnsm  generates  a  different  file  name  each  time  it  is  called. 

Files  created  using  tmpnam  and  either  /open  or  ereat  are  only  temporary  in  the  sense  that  they 
reside  in  a  directory  intended  for  temporary  use,  and  their  names  are  unique.  It  is  the  user’s 
responsibility  to  use  ttnltnit(2)  to  remove  the  file  when  its  use  is  ended. 

SEE  ALSO 

creat(2),  ttnlink(2),  mktemp(3),  fopen(3S) 

BUGS 

If  called  more  than  17,676  times  in  a  single  process,  tmpnam  will  start  recycling  previously  used 
names. 

Between  the  time  a  file  name  is  created  and  the  file  is  opened,  it  is  possible  for  some  other  process 
to  create  a  file  with  the  same  name.  This  can  never  happen  if  that  other  process  is  using  tmpnam 
or  mtfemp,  and  the  .file  names  are  chosen  so  as  to  render  duplication  by  other  means  unlikely. 


Sun  Release  1.1 


Last  change:  26  August  1983 


11 


ULIMIT(3C) 


COMPATIBILITY  ROUTINES 


ULIMIT(3C) 


NAME 

ulimit  -  get  and  set  user  limits 
SYNOPSIS 

long  u]lmlt(emd,  newUmlt) 

Int  cmdi 

DESCRIPTION 

This  fiinetlon  !•  Included  for  eyetem-III  eompnilblllty,  and  le  obeoleted  by  $etrlimit{2). 
This  function  provides  for  control  over  process  limits.  The  cmd  values  avaQable  are: 

1  Get  the  process’s  file  size  limit.  The  limit  is  in  units  of  512>byte  blocks  and  is  inherited 
by  child  processes.  Files  of  any  size  can  be  read. 

2  Set  the  process’s  file  size  limit  to  the  value  of  newlimit.  Any  process  may  decrease  this 
limit,  but  only  a  process  with  an  effective  user  ID  of  super>user  may  increase  the  limit. 
Ulimit  will  fail  and  the  limit  will  be  unchanged  if  a  process  with  an  effective  user  ID  other 
than  the  super-user  attempts  to  increase  its  file  size  limit. 

8  Get  the  maximum  possible  break  value.  See  irk(2). 

RETURN  VALUE 

Upon  successful  completion,  a  non-negative  value  is  returned.  Otherwise  a  value  of  -1  is  returned 
and  errno  is  set  to  indicate  the  enor. 

SEE  ALSO 

brk(2),  8etrlimit(2),  write(2) 
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UTIME(3C) 


COMPATIBILITY  ROUTINES 


UTIME(3C) 


NAME 

utime  -  set  file  times 
SYNOPSIS 

#!nclud«  <sys/type««h> 

utlnie(flle,  tlmep) 
char 

timejt  tlmep(2]} 

DESCRIPTION 

This  interfaee  is  obsoleted  by  utlines(2). 

The  utime  call  uses  the  ‘accessed’  and  ‘updated’  times  in  that  order  from  the  timep  vector  to  set 
the  corresponding  recorded  times  for  file. 

The  caller  must  be  the  owner  of  the  file  or  the  super-user.  The  ‘inode-changed’  time  of  the  file  is 
set  to  the  current  time. 

SEE  ALSO 

utime8(2),  8tat(2) 
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VLIMIT(3C) 


COMPATIBILITY  ROUTINES 


VLIMIT(3C) 


NAME 

vlimit  -  control  maKimum  system  resource  consumption 


SYNOPSIS 

#inelude  <«ys/vllnilt.h> 
v]Imtt(resonree,  value) 


DESCRIPTION 

Thin  faelUty  Is  superseded  by  Ketr)liiitt())* 

Limits  the  consumption  by  the  current  process  and  each  process  it  creates  to  not  individuaUy 
exceed  vs/ue  on  the  specified  rtsourct.  If  voluc  is  specified  as  -»t^then  the  current  limit  is  returned 
and  the  limit  is  unchanged.  The  resources  which  are  ciHrently  controU^le  are: 


LIMJ^ORAISB 

A  pseudo^-Kmit;  if  set  non-zero  then- the  Itmfts-may  not  be  raised.  Only  the 
super-user  may  remove  the  aoraite  restrfetioa.. 

LIMjCPU  .  the  maximum  number  of  epu^econds  to  be  used  by  each  process 
LIM_FSI2B  the  largest  single  file'which  can-be  created 

the  maximum  growth  of  the  datwf  stack  regkm  via  «tri<2)  beyond  the  end  of 
the  program  text. 


1#IM:;.STACK  the  maximum  size  oMhe  automatienHy-extended  stack  regi<m 
LIMjCORB  the  size  of  the  Imgest  cote  duoqi  thatwift  be  created. 

LIMJIlAXHSB 

a  soft  limit  for  the  amount  otpEysical  memmy  (m  bytes)  to^  be  given  to  the  pro¬ 
gram.  If  memory  » tight,  the  system  will  prefier  to  take  memory  from  processes 
which  ate  exceeding  their-declared  LIMJMAXRSS. 


Because  this  information  is  stored  in  the  per-process  information  this  system  call  must  be  exe¬ 
cuted  direct^  by  the  shell  if  it  is  to  affect  all  future  processes  created  by  the  shell;  ffmil  is  thus  a 
built-in  command  to  crA|l). 

The  system  refuses  to  extenii  the  data  or  stack  space  when  the  limits  would  be  exceeded  in  the 
normal  waypa  breai  call  fails  if  Che  data  space  limit  is  reached,  or  the  process  is  killed  when  the 
stack  limit  is  reached  (since  the  stack  cannot  be  extended,  there  is  no  way  to  send  a  signall). 

A  file  i/o  operation  which  would  create  a  file  which  is  too  large  wiU  cause  a  signal  SIQXFSZ  to  be 
generated,  this  normally  terminates  the  process,  bnt  may  be  caught.  When  the  cpu  time  limit  is 
exceeded,  a  signaT  SIGXCPU  is  sent  to  the  (lending  process;  to  allow  it  time  to  process  the  signal 
it  is  given  &  seconds  grace  by  raising  the  cpu-time  limit. 


SEE  ALSa 

C8h(l) 


BUGS 

Itl,tKU^ORAISE.is  set,  then  uo  grace  should  be  given  when  tie  cpu-time  limit  is  exceeded^ 
There  should  be  ftmtf  and  tmfrmtt  commands  in  sh^)  as  well  an  In  csA. 
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VTIMES(3C) 


COMPATIBILITY  ROUTINES 


VTIMES(3C) 


NAME 

vtimes  -  get  information  about  resource  utilization 

SYNOPSIS 

vtlme8(par_vmt  ch.vm) 
struct  vtimes  *par_vmf  *cli_vm| 

DESCRIPTION 

This  facility  Is  superseded  by  getrusage(2). 

Vtimef  returns  accounting  information  for  the  current  process  and  for  the  terminated  child 
processes  of  the  current  process.  Either  par_vm  or  ck_vm  or  both  may  be  0,  in  which  case  only 
the  information  for  the  pointers  which  are  non«zero  is  returned. 

After  the  call,  each  buffer  contains  information  as  defined  by  the  contents  of  the  include  file 
struct  vtimes  { 

int  vm_utime;  /*  User  time  (*HZ)  */ 

int  vmjBtime;  /*  system  time  (*HZ)  */ 

/*  divide  next  two  by  utime+  stime  to  get  averages  */ 
unsigned  vmjdsrss;  /*  integral  of  d+  s  rss  */ 

unsigned  vmjxrss;  /*  integral  of  text  rss  */ 

int  vm_maxrs8;  /*  maximum  rss  •/ 

int  vm^ajflt;  /*  major  page  faults  */ 

int  vm  jninflt;  /*  minor  page  faults  */ 

int  vmjBwap;  /*  number  of  swaps  •/ 

int  vmjnblk;  /*  block  reads  •/ 

int  vm_oubllt;  /*  block  writes  •/ 

); 

The  vm_uftme  and  vmjstime  fields  give  the  user  and  system  time  respectively  in  60ths  of  a  second 
(or  60ths  if  that  Is  the  frequency  of  wall  current  in  your  locality.)  The  vm_»ifrs«  and  vm_ixr$8 
measure  memory  usage.  They  are  computed  by  integrating  the  number  of  memory  pages  in  use 
each  over  epu  time.  They  are  reported  as  though  computed  discretely,  adding  the  current 
memory  usage  (in  512  byte  pages)  each  time  the  clock  ticks.  If  a  process  used  5  core  pages  over  1 
cpu'second  tot  its  data  and  stack,  then  vm_iJ8r88  would  have  the  value  5*60,  where 
vm_8lime  would  be  the  60.  Vm^id8r88  integrates  data  and  stack  segment  usage,  while 
tim_tarsr  integrates  text  segment  usage.  Vm^mazr88  reports  the  maximum  instantaneous  sum  of 
the  text+  data+  stack  core«resident  page  count. 

The  vmjmajflt  field  gives  the  number  of  page  faults  which  resulted  in  disk  activity;  the  vmjminflt 
field  gives  the  number  bf  page  faults  incurred  in  simulation  of  reference  bits;  vmjnswap  is  the 
number  of  swaps  which  occurred.  The  number  of  file  system  input/output  events  are  reported  in 
vtn_inb{k  and  vm_oublk  These  numbers  account  only  for  real  i/o;  data  supplied  by  the  caching 
mechanism  is  charged  only  to  the  first  process  to  read  or  write  the  data. 

SEE  ALSO 

getrusage(2),  wait3(2) 
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INTRO  (3M) 


MATHEMATICAL  FUNCTIONS 


INTRO  (3M) 


NAME 

intro  -  introduction  to  mathematical  library  functions 
DESCRIPTION 

These  functions  constitute  the  math  library,  libm.  They  are  automatically  loaded  as  needed  by 
the  Fortran  compiler  /77(1).  The  link  editor  searches  this  libraiy  under  the  “-Im”  option. 
Declarations  for  these  functions  may  be  obtained  from  the  include  file  <math.h>. 

LIST  OP  FUNCTIONS 


Name 

Appeare  on  Page 

Deeeription 

acos 

sin  .3m 

trigonometric  functions 

asin 

sin  .3m 

trigonometric  functions 

atan 

sin.3m 

trigonometric  functions 

atan2 

sin  .3m 

trigonometric  functions 

cabs 

hypot.Sm 

Euclidean  distance 

ceil 

floor.Sm 

absolute  value,  floor,  ceiling  functions 

cos 

sin  .dm 

trigonometric  functions 

cosh 

sinh.dm 

hyperbolic  functions 

exp 

exp.3m 

exponential,  logarithm,  power,  square  root 

fabs 

fioor.Sm 

absolute  value,  floor,  ceiling  functions 

fioor 

fioor.Sm 

absolute  value,  floor,  ceiling  functions 

gamma 

gamma.3m 

log  gamma  function 

bypot 

hypot.Sm 

Euclidean  distance 

jO 

j0.3m 

bessel  functions 

jl 

j0.3m 

bessel  functions 

in 

j0.3m 

bessel  functions 

log 

exp.Sm 

exponential,  logarithm,  power,  square  root 

loglO 

exp.Sm 

exponential,  logarithm,  power,  square  root 

pow 

exp.Sm 

exponential,  logarithm,  power,  square  root 

sin 

*  8in.3m 

trigonometric  functions 

sinh 

smh.Sm 

hyperbolic  functions 

sqrt 

exp.Sm 

exponential,  logarithm,  power,  square  root 

tan 

sin. 3m 

trigonometric  functions 

tank 

sinb.Sm 

hyperbolic  functions 

yo 

j0.3m 

bessel  functions 

yi 

j0.3m 

bessel  functions 

yn 

j0.3m 

bessel  functions 

Q 
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EXP(3M) 


MATHEMATICAL  FUNCTIONS 


EXP(3M) 


NAME 

exp,  log,  loglO,  pow,  Bqrt  -  exponential,  togarithm,  power,  square  root 

SYNOPSIS 

#include  <math.h> 

double  exp(x) 
double  x| 

double  log(x) 
double  x| 

double  IoglO(x) 
double  X] 

double  pow(Xf  y) 
double  X,  yt 

double  Bqrt(x) 
double  x; 

DESCRIPTION 

Evp  returns  the  exponential  function  of  x. 

Itog  returns  the  natural  logarittot  of  xi  toglO  returns  the  base  10  logarithm. 

Pow  returns 

Sgrt  returns  the  square  root  of  x. 

SEE  ALSO 

hypot(3M),  sinh(3M),  intto(2) 

DIAGNOSTICS 

Eixp  and  pow  return  a  huge  value  when  the  ewrect  value  would  overflow;  errno  is  set  to 
ERANGE.  Pow  returns  0  and  sets  errno  to  EDOM  when  the  second  argument  is  negative  and 
non>integral  and  when  both  arguments  are  0. 

Log  returns  0  when  x  is  zero  or  negative;  errno  is  set  to  EDOM. 

Sgrt  returns  0  when  x  is  negative;  errno  is  set  to  EDOM. 
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MATHEMATICAL  FUNCTIONS 


FLOOR  (3M) 


NAME 

fabs,  floor,  ceU  -  absolute  value,  floor,  ceiling  functions 

SYNOPSIS 

^Include  <msth,h> 

double  floor(x) 
double  x| 

double  cell(x) 
double  x| 

double  fab8(x) 
double  X| 

DESCRIPTION 

Fah$  returns  the  absolute  value  |  x  |. 

Floor  returns  the  largest  integer  not  greater  than  x. 

Ceil  returns  the  smallest  integer  not  less  than  x. 

SEE  ALSO 
abs(3) 

BUGS 

The function  is  actually  in  the  standard  C  library,  and  should  be  moved  to  the  math  library. 
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GAMMA  (3M) 


MATHEMATICAL  FUNCTIONS 


GAMMA(3M) 


NAME 

gamma  -  log  gamma  function 
SYNOPSIS 

#Inelude  <math.h> 

double  gainma(x) 
double  xt 

DESCRIPTION 

Gamma  returns  In  |r(|x|)|.  The  sign  of  r(|al.)  »  letorned  ii 
The  following  C  program  might  be  used  to  calei^te  F: 

y  gaRmia(x); 

#ffdef  Tax 

tf(y  >  88.0) 

#endif 
#ifdef  sun 

if(y  >  mo) 

#eadif 

error(); 
y  =»  exp(y); 
iffsigttgam) 

y  -  -y; 

DIAGNOSTICS 

A  huge  value  is  returned  for  negative  integer  arguments. 

BUGS 

There  should  be  a  positive  indication  of  error. 
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HYP0T(3M) 


MATHEMATICAL  FUNCTIONS 


H\TOT(3M) 


NAME 

bypot,  cabt  -  Euclidean  distance 

SYNOPSIS 

#lneluda  <mnth*h> 

double  hypot(x,  y) 
doubl*  yt 

double  eaba(i) 
etruet  {  double  Xy  y}}  a) 

DESCRIPTION 

tfyy eland  ca^s return 

aqrt(x*x  +  y*y)f 

taking  precautions  against  unwarranted  overflows. 

SEE  ALSO 

exp(3M)  for  tqrt 
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J0(3M) 


MATHEMATICAL  FUNCTIONS 


J0(3M) 


NAME 

jO,  jl,  io,  yO,  yl,  ya  >  bessel  fuaetioDB 

SYNOPSIS 

#lnelud«  <in*th.k> 

double  JO(x) 
double  xy 

dottble  Jl(x) 
double  x| 

double  Jn(n»  x) 
double  X) 

double  y0(i4 
double  xf 

double  )rl(x) 
double  X( 

double  yn(nt  x)^ 
double  x( 

DESCRIPTION 

These  functioas  calculate  Bessel  functions  of  the  first  and  second  kinds  for  real  arguments  and 
integer  orders. 

DIAGNOSTICS 

Negative  arguments  cause  yO,  yt,  and  yn  to  return  a  huge  negative  value  and  set  errno  to  EDOM. 
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MATHEMATICAL  FUNCTIONS 


SIN(3M) 


NAME 

sin,  cos,  tfts,  asin,  aeos,  atan,  atan2  -  trigonometric  functions 

SYNOPSIS 

#lnelud«  <math.h> 

double  aln(x) 
double  x| 

double  co8(x) 
double  X) 

double  asln(x) 
double  x{ 

double  «eos(x) 
double  x| 

double  •tsn(x) 
double  X) 

double  «tan2(xt  y) 
double  X,  y| 

DESCRIPTION 

Sin,  eot  and  tan  return  trigonometric  functions  of  radian  arguments.  The  magnitude  of  the  argu¬ 
ment  should  be  checked  by  the  caller  to  make  sure  the  result  is  meaningful. 

Asin  returns  the  arc  sin  in  the  range  -ff/2  to  jr/2. 

Aeoa  returns  the  arc  cosine  in  the  range  0  to  x. 

Atan  returns  the  arc  tanjent  of  x  in  the  range  -?r/2  to  ff/2. 

AtanS  returns  the  arc  tangent  of  z/y  in  the  range  -it  to  it. 

DIAGNOSTICS 

Arguments  of  magnitude  greater  than  1  cause  sstn  and  acoa  to  return  value  0;  errno  is  set  to 
EDOM.  The  value  of  tan  at  its  singular  points  is  a  huge  number,  and  errno  is  set  to  ERANGE. 

BUGS 

The  value  of  tan  for  arguments  greater  than  about  2**31  is  garbage. 
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NAME 

einb,  coab,  tanb  -  hyperbolic  functiooi 
SYNOPSIS 

#inelude  <math.h> 
double  8lnb(x) 

double  eosh(x) 
double  x) 

double  tanh(x) 
double  X) 

DESCRIPTION 

These  fttuctions  compute  the  designated  hyperbrdic  functions  for  real  arguments. 
DIAGNOSTICS 

Sinh  and  eeeh  return  a  huge  value  of  appropriate  sign  when  the  correct  value  would  overflow. 
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INTRO  (3N) 


intro  -  introduction  to  network  library  functions 

are  applicable  to  the  DARPA  Internet  network,  which  are 


NAME 
DESCRIPTION 

This  section  describes  functions  that 
part  of  the  standard  C  library. 

LIST  OF  FUNCTIONS 


Name  • 

Appears  on  Page 

endhostent 

getbostent.3n 

endnetent 

getnetent.Sn 

endprotoent 

getprotoent.3n 

endservent 

getservent.3n 

gethostbyaddr 

gethoetent.3n 

gethostbyname 

getbo8tent.3n 

gethostent 

getbostent.3n 

getnetbyaddr 

getnetent.3n 

getnetbyname 

getnetent.3n 

getnetent 

getnetent.3n 

getprotobyname 

getprotoent.3n 

getprotobynumber 

getprotoent.3n 

getprotoent 

getprotoent.Sn 

getservbyname 

getservent.3n 

getservbyport 

getBervent.3n 

getservent 

get8ervent.3n 

htonl 

byteorder.3n 

htons 

byteorder.3n 

inet_addr 

inet.3n 

inetjnaof 

inet.3n 

inet_inakeaddr 

inet.3n 

inet_netof 

inet.3n 

inetjietwork 

inet.3n 

inet_ntpa 

inet.3n 

ntobl 

byteorder.Sn 

ntohs 

byteorder.Sn 

rcmd 

rcmd.3n 

rexec 

rexec.3n 

rresvport 

rcmd.Sn 

ruserok 

rcmd.3n 

sethostent 

gethostent.3a 

setnetent 

getnetent.3n 

setprotoent 

getprotoent.3n 

setservent 

get8eivent.3n 

Description 

get  network  host  entry 
get  network  entry 
get  protocol  entry 
get  service  entry 
get  network  host  entry 
get  network  host  entry 
get  network  host  entry 
get  network  entry 
get  network  entry 
get  network  entry 
get  protocol  entry 
get  protocol  entry 
get  protocol  entry 
get  service  ent^ 
get  service  entry 
get  service  entry 

convert  values  between  host  and  network  byte  order 

convert  values  between  host  and  network  byte  order 

Internet  address  manipulation 

Internet  address  manipulation 

Internet  address  manipulation 

Internet  address  manipulation 

Internet  address  manipulation 

Internet  address  manipulation 

convert  v^ues  between  host  and  network  byte  order 

convert  values  between  host  and  network  byte  order 

routines  for  returning  a  stream  to  a  remote  command 

return  stream  to  a  remote  command 

routines  for  returning  a  stream  to  a  remote  command 

routines  for  returning  a  stream  to  a  remote  command 

get  network  host  entry 

get  network  entry 

get  protocol  entry 

get  service  entry 
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NAME 

htonl,  htotts,  ntohl,  Btoha  -  convert  values  between  host  and  network  byte  order 
SYNOPSIS 

#lnelud«  <8ya/types.h> 

#inclttde  <ttetlBet/lii.h> 

netlong  »  htonl(hostloDg)| 
u^long  aetlongt  hosilongt 

notahork  s  htons(hoatshort)t 
u  jdiort  netshort»rbeetsbort) 

hostlong  aa  ntohl(netlong)| 
ujlong  hoatkmgi  netlongi 

hostshort  =■  ntohs(netshort)} 
ujibort  bostsborti  netsbortr 

DESCRIPTION 

These  routines  eonvert  16  and  32  bit  quantities  between  network  byte  order  and  host  byte  order. 
On  machnes  such  as  the  Sun  these  routtaes  are  defined  as  null  macros  in  the  include  file 
<netinet/in.k>. 

These  routines  are  most  often  used  in  conjunction  with  Internet  addresses  and  ports  as  returned 
by  yeiAcsIeni(3Nj  and  pe<csmn((3N). 

SEE  ALSO 

8ethostent(3N),  gctservent(3N) 

BUGS 

The  VAX  handles  bytes  backwards  from  most  everyone  else  in  the  world.  This  is  not  expected  to 
be  fixed  m  the  near  future. 
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NAME 

gethoiteiit,  gethostbyaddr,  gethoetbyname,  sethostent,  endhostent  -  get  network  host  entry 
SYNOPSIS 

#lnelude  <netdbJi> 

■truet  honiont  ^gethoatentQ 

struct  hostent  *g«thostbyn»in«(nsme) 
ehsr  *nsme} 

struct  hostent  *gsthostbyaddr(sddrt  lcn»  type) 
ch»r  *addr|  Int  Isn,  typsi 

ssthost«it(stsyopsn) 

Int  stayopon 

sndhostsntO 

DESCRIPTION 

Oethottent,  gethotf byname,  and  gethoetbyaddr  each  return  a  pointer  to  an  object  with  the  follow¬ 
ing  structure  containing  the  broken-out  fields  of  a  line  in  the  network  host  data  base,  fetejhoett. 

struct  hostent  { 

char  *hjiaine;  /*  official  name  of  host 
char  •*h_alia8e8;  /•  alias  list  */ 

int  h_addrtype;  f*  address  type  •/ 

int  hjength;  /*  length  of  address  */ 

char  *h_addr;  /•  address  ♦/ 

}; 

The  members  of  this  structure  are: 
hjtame  Official  name  of  the  host. 

h^aliases  A  sero  termtoated  array  of  alternate  names  for  the  host, 
hjaddrtype  The  type  of  address  being  returned;  currently  always  AF^INET. 
hjength  The  length,  in  bytes,  of  the  address. 

h_addr  A  pointer  to  the  network  address  for  the  host.  Host  addresses  are  returned  in  net¬ 
work  byte  order. 

Gethoatent  reads  the  next  line  of  the  file,  opening  the  file  if  necessary. 

Sethoftent  opens  and  rewinds  the  file.  If  the  tlayopen  Bag  is  non-zero,  the  host  data  base  will  not 
be  closed  after  each  call  to  gethoetent  (either  directly,  or  indirectly  through  one  of  the  other 
“gethost"  calls). 

Endhottent  closes  the  file. 

Oethettbyname  and  gethoetbyaddr  sequentially  search  from  the  beginning  of  the  file  until  a  match¬ 
ing  host  name  or  host  address  is  found,  or  until  EOF  is  encountered.  Host  addresses  are  supplied 
In  network  order. 

FILES 

/ete/hosts 

SEE  ALSO 

hosts(6) 

DIAGNOSTICS 

Null  pointer  (0)  returned  on  EOF  or  error. 
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BUGS 

All  mfonnatioD  is  contained  in  a  static  area  so  it  must  be  copied  if  it  is  to  be  saved.  Only  the 
Internet' address  format  is  currently  understood. 
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NAME 

getnetent,  getnetbyaddr,  getnetbyname,  setnetent,  endnetent  -  get  network  entry 
SYNOPSIS 

#lnelude  <netdb.h> 
struct  netent  ^getnetentO 

struct  netent  *getnetbynAme(nsme) 
chsr  *naine| 

struct  netent  *getnetbyaddr(net,  type) 
long  net} 

Betnetent(Bt«yopen) 
int  stayopen 

endnetent() 

DESCRIPTION 

Getnetent,  getnetbyname,  and  getnetbyaddr  each  return  a  pointer  to  an  object  with  the  following 
structure  containing  the  broken-out  fields  of  a  line  in  the  network  data  base,  /  etc/  networks. 

struct  netent  { 


char 

*n_name; 

/*  official  name  of  net  */ 

char 

**n_alia8es; 

/*  alias  list  */ 

int 

n_addrtype; 

/•  net  number  type  •/ 

long 

njaet; 

/•  net  number  •/ 

}; 

The  members  of  this  structure  are: 
n_name  The  official  name  of  the  network. 

n^aliasea  A  aero  terminated  list  of  alternate  names  for  the  network, 
njaddrtype  The  type  of  the  network  number  returned;  currently  only  AF_INET. 
n^et  The  network  number.  Network  numbers  are  returned  in  machine  byte  order. 

Getnetent  reads  the  next  line  of  the  file,  opening  the  file  if  necessary. 

Setnetent  opens  and  rewinds  the  file.  If  the  etayopen  flag  is  non-zero,  the  net  data  base  will  not  be 
closed  after  each  call  to  getnetent  (either  directly,  or  indirectly  through  one  of  the  other  “getnet” 
calls). 

Endnetent  closes  the  file. 

Getnetbyname  and  getnetbyaddr  sequentially  search  from  the  beginning  of  the  file  until  a  matching 
net  name  or  net  address  is  found,  or  until  EOF  is  encountered.  Network  numbers  are  supplied  in 
host  order. 

FILES 

/etc/networks 

SEE  ALSO 

oetworkB(6) 

DIAGNOSTICS 

Null  pointer  (0)  returned  on  EOF  or  error. 

BUGS 

All  information  is  contained  in  a  static  area  so  it  must  be  copied  if  it  is  to  be  saved. 

Only  Internet  network  numbers  ue  currently  understood. 


Sun  Release  1.1 


Last  change:  9  March  1984 


5 


GETPROTOENT(3N) 


NETWORK  FUNCTIONS 
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NAME 

getprotoent,  getprotobynumber,  getprotobyname,  setprotoent,  endprotoent  -  get  protocol  entry 
SYNOPSIS 

#lnctude  <netdbib> 
struet  protoent  *getprotoetiiQ 

■truet  protoent  *ge^rotobyname^wine) 
char  *naine| 

atritei  protoent  *getprj)tobynunibw(proto) 

Int  proto} 

•etprotoent(Btayopen)' 
lot  etayopen 

emfprotoentQ 

DESCRIPTfCm 

Getprctoent,  getprotahifndme,  and  getpfctolvnumber  twh  return  a  pointer  to  an  object  with  the 
following  Btracture  containing  the  broken>oat  fielda  of  a  line  in  the  network  protocol  data  base, 
/  etefprotpeoH. 

struct  protoent  { 

char  *p_patne;  /*  officiaf  name  of  protocol  */ 

char  ••p_aliase8;  /•  alias  lirt  •/ 

long  p_proto;  /•  protocol  number  */ 

Tbe  members  of  this  structure  are: 
p^name  Tbe  official  name  of  the  protocol. 

pjaliases  A  zero  terminated  list  of  alternate  names  for  the  protocol, 
p^proto  The  protocol  number. 

Getprotoent  reads  the  next  line  of  the  file,  opening  the  file  if  necessaiy. 

Setprotoent  opens  and  rewinds  the  file.  If  the  stayopen  flag  is  non-zero,  the  net  data  base  will  not 
be  closed  after  each  call  to  getprotoent  (either  directly,  or  indirectly  through  one  of  the  other 
**getproto”  calls). 

Endprotoent  closes  the  file. 

Getprotobyname  and  getprotobynumber  sequentially  search  from  the  beginning  of  the  file  until  a 
matching  protocol  name  or  protocol  number  is  found,  or  until  EOF  is  encountered. 

FILES 

/etc/protocols 

SEE  ALSO 

protocol8(5) 

DIAGNOSTICS 

Null  pointer  (0)  returned  on  EOF  or  error. 

BUGS 

All  information  is  contained  in  a  static  area  so  it  must  be  copied  if  it  is  to  be  saved.  Only  the 
Internet  protocols  are  currently  understood. 
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NAME 

getservent,  getservbyport,  getservbyname,  eetservent,  endservent  -  get  service  entry 
SYNOPSIS 

#lnelud«  <netdb.b> 
struct  servent  *getserventO 

struct  servent  *getservbyn«me(n»nie,  proto) 
char  ^neme,  *proto) 

struct  servent  *getservbyport(port|  proto) 

Int  port}  char  *proto} 

setservent(st«yopen) 

Int  stayopen 

endserventO 

DESCRIPTION 

Gettervent,  gctaervbyname,  and  gettervbyport  each  return  a  pointer  to  an  object  with  the  following 
structure  containing  the  broken-out  fields  of  a  line  in  the  network  services  data  base, 
f  etc/ tervicet. 

struct  servent  { 


char 

*s_name; 

/*  official  name  of  service  */ 

char 

**B_alia8es; 

/*  alias  list  */ 

long 

s_port; 

/*  port  service  resides  at  */ 

char 

•8_proto; 

/*  protocol  to  use  */ 

}; 


The  members  of  this  structure  are: 
s_}isme  The  official  name  of  the  service. 

s.aliases  A  tero  terminated  list  of  alternate  names  for  the  service. 

s_port  The  port  number  at  which  the  service  resides.  Port  numbers  are  returned  in  network 
byte  order. 

sjproto  The  name  of  the  protocol  to  use  when  contacting  the  service. 

Get$ervent  reads  the  next  line  of  the  file,  opening  the  file  if  necessary. 

Seteervent  opens  and  rewinds  the  file.  If  the  ttapopen  flag  is  non-zero,  the  net  data  base  will  not 
be  closed  after  each  call  to  gettervent  (either  directly,  or  indirectly  through  one  of  the  other  “get- 
serv"  calls). 

Endtervenl  closes  the  file. 

Getservbyname  and  getservbyport  sequentially  search  from  the  beginning  of  the  file  until  a  match¬ 
ing  protocol  name  or  port  number  is  found,  or  until  EOF  is  encountered.  If  a  protocol  name  is 
also  supplied  (non-NULL),  searches  must  also  match  the  protocol. 

FILES 

/etc/services 
SEE  ALSO 

getprotoent(3N),  Bervice8(5) 

DIAGNOSTICS 

Null  pointer  (0)  returned  on  EOF  or  error. 

BUGS 

All  information  is  contained  in  a  static  area  so  it  must  be  copied  if  it  is  to  be  saved.  Expecting 
port  numbers  to  fit  in  a  32  bit  quantity  is  probably  naive. 
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name  .  ....  ,  .  .  jj  - 

inet_addr,  iiiet_iietwork,  inet_tnskead<lr,  inetjnaof,  inetjietof,  inet_Btoa  -  Internet  address 

manipulation 

SYNOPSIS 

#inelude  <8ys/aoeketJi> 

#lneludn  <netlnet/tn.h> 

#lnelude  <Mpn/liiet.h> 

•truet  In^sddr 
ln«t_SMldr(ep) 
chan  *epi 

lot 

tnet^network(ep) 
char  *ep) 

■truet  In_addr 
lnet.jnskesuldr(a«t,  Ina) 

Int^nnt,  Inai 

Int 

ln«tJnaof(In) 

■tract  Injaddr  Inf 

Int 

In«t_netof(lD) 

■truet  ln_itddr  Inp 

ehar  * 

Inetjatoa(ln) 

■truet  In_addr  In} 

DESCRIPTION 

The  routines  inet_(tddr  and  inetjnetwork  each  interpret  character  strings  representing  numbers 
expressed  in  the  Internet  standard  notation,  returning  numbers  suitable  for  use  as  Internet 
addresses  and  Internet  network  numbers,  respectively.  The  routine  inet^makeaddr  takes  an  Inter¬ 
net  network  number  and  a  local  network  address  and  constructs  an  Internet  address  from  it.  The 
routines  inet^netof  and  inetjnaof  break  apart  Internet  host  addresses,  returning  the  network 
number  and  local  network  address  part,  respectively. 

The  routine  inef_nioa  returns  a  pointer  to  a  string  in  the  base  256  notation  "d.d.d.d”  described 
below. 

All  Internet  address  are  returned  in  networic  order  (bytes  ordered  from  left  to  right).  All  network 
numbers  and  local  address  parts  are  returned  as  machine  format  integer  values. 

INTERNET  ADDRESSES 

Values  specified  using  the  notation  take  one  of  the  following  forms: 
a.b.c.d 
a.b.c 
a.b 
a 

When  four  parts  are  specified,  each  is  interpreted  as  a  byte  of  data  and  assigned,  from  left  to 
right,  to  the  four  bytes  of  an  Internet  address.  Note  that  when  an  Internet  address  is  viewed  as  a 
32-bit  integer  quantity  on  the  VAX  the  bytes  referred  to  above  appear  as  “d.c.b.a".  That  is, 
VAX  bytes  are  ordered  from  right  to  left. 

When  a  three  part  address  is  specified,  the  last  part  is  interpreted  as  a  16-bH  quantity  and  placed 
in  the  right  most  two  bytes  of  the  network  address.  This  makes  the  three  part  address  format 
convenient  for  specifying  Class  B  network  addresses  as  ‘'128.net.host”. 
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When  a  two  part  address  is  supplied,  the  last  part  is  interpreted  as  a  24-bit  quantity  and  placed 
in  the  right  most  three  bytes  of  the  network  address.  This  makes  the  two  part  address  format 
convenient  for  specifying  Class  A  network  addresses  as  “net.host”. 

When  only  one  part  is  given,  the  value  is  stored  directly  in  the  network  address  without  any  byte 
rearrangement. 

All  numbers  supplied  as  “parts”  in  a  notation  may  be  decimal,  octal,  or  hexadecimal,  as 
specified  in  the  C  language  (i.e.  a  leading  Ox  or  OX  implies  hexadecimal;  otherwise,  a  leading  0 
implies  octal;  otherwise,  the  number  is  interpreted  as  decimal). 

SEE  ALSO 

getho8tent(3N),  getnetent(3N),  ho6t8(5),  network8(5), 

DIAGNOSTICS 

The  value  -1  is  returned  by  inet_addr  and  inetjnetwork  for  malformed  requests. 

BUGS 

The  problem  of  host  byte  ordering  versus  network  byte  ordering  is  confusing.  A  simple  way  to 
specify  Class  C  network  addresses  in  a  manner  similar  to  that  for  Class  B  and  Class  A  is  needed. 

The  return  value  from  inetjntoa  points  to  static  information  which  is  overwritten  in  each  call. 
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NAME 

rcmd,  rresvporti,  rueerok  -  routines  for  returning  a  stream  to  a  remote  command 
SYNOPSIS 

rem  =a  remd(ahoat|  Inport,  loeuser,  remuser,  emd»  fd2p)} 
char  **ahoBt{ 
ttjihort  tnport} 

char  *loeasar«  *r«musery  *eindf 
Int  *fd2p| 

a  «■  rresTport(port)| 
tnt  *port| 

ruMrok(rhoBtt  Buperustr*  rutcr»  luser)) 
char  "'rhosti 
Int  Buperuseri 
char  *ruMr»  *Iuaer| 

DESCRIPTION 

Jtemd  is  a  routine  used  by  the  super-user  to  execute  a  command  on  a  remote  machine  using  an 
authentication  scheme  baaed  on  reserved  port  numbers.  Hreevport  is  a  routine  which  returns  a 
descriptor  to  a  socket  with  an  address  in  the  privileged  port  space.  Ruserok  is  a  routine  used  by 
servers  to  authenticate  clients  requesting  service  with  remi.  All  three  functions  are  present  in  the 
same  file  and  are  used  by  the  rrAd(8C)  server  (among  others). 

Remd  looks  up  the  host  *aho8t  using  yeIAo«(iyRame(3N),  returning  -1  if  the  host  does  not  exist. 
Otherwise  *aho8t  is  set  to  the  standard  name  of  the  host  and  a  connection  is  established  to  a 
server  residing  at  the  well-known  Internet  port  tnporl. 

If  the  call  succeeds,  a  socket  of  type  SOCK_STREAM  is  returned  to  the  caller,  and  given  to  the 
remote  command  as  stdln  and  stdout.  If  fdSp  is  non-zero,  then  an  auxiliary  channel  to  a  control 
process  will  be  set  up,  and  a  descriptor  for  it  will  be  placed  in  *fdSp.  The  control  process  will 
return  diagnostic  output  from  the  command  (unit  2)  on  this  channel,  and  will  also  accept  bytes  on 
this  channel  as  being  UNIX  signal  numbers,  to  be  forwarded  to  the  process  group  of  the  com¬ 
mand.  If  fdSp  is  0,  then  the  stderr  (unit  2  of  the  remote  command)  will  be  made  the  same  as  the 
stdout  and  no  provision  is  made  for  sending  arbitrary  signals  to  the  remote  process,  although  you 
may  be  able  to  get  its  attention  by  using  out-of-band  data. 

The  protocol  is  described  in  detail  in  r«h(f(8C). 

The  Tre8vpori  routine  is  used  to  obtain  a  socket  with  a  privileged  address  bound  to  it.  This 
socket  is  suitable  for  use  by  rcmd  and  several  other  routines.  Privileged  addresses  consist  of  a 
port  in  the  range  0  to  1023.  Only  the  super-user  is  allowed  to  bind  an  address  of  this  sort  to  a 
socket. 

Ruserok  takes  a  remote  host’s  name,  as  returned  by  a  0etkos(ent(3N)  routine,  two  user  names  and 
a  fiag  indicating  if  the  local  user's  name  is  the  super-user.  It  then  checks  the  files  f  etef  ko8i8.eguiv 
and,  possibly,  .rho8t8  in  the  current  working  directory  (normally  the  local  user’s  home  directory) 
to  see  if  the  request  for  service  is  allowed.  A  1  is  returned  if  the  machine  name  is  listed  in  the 
"hosts.equiv”  file,  or  the  host  and  remote  user  name  are  found  in  the  “.rhosts”  file;  otherwise 
ruserok  returns  0.  If  the  superuser  flag  is  1,  the  checking  of  the  “host.equiv”  file  is  bypassed. 

SEE  ALSO 

rlogin(lC),  rsh(lC),  rcxec(3N),  rexecd(8C),  rlogind(8C),  r8bd(8C) 

BUGS 

There  is  no  way  to  specify  options  to  the  socket  call  which  rcmd  makes. 
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NAME 

rexcc  -  return  stream  to  a  remote  command 
SYNOPSIS 

rem  a  rexee(ahoat,  Inport,  uaer,  paaawd,  emd,  fd2p)| 

char  **ahoat] 

u_^hort  Inporti 

ebar  *uier,  *pafawd,  *emd| 

lot  *fdSpi 

DESCRIPTION 

Rtxtc  looks  up  the  host  *aho8t  using  jreIAoeIijmsme(3N),  returning  -1  if  the  host  does  not  exist. 
Otherwise  *aho»t  is  set  to  the  standard  name  of  the  host.  If  a  username  and  password  are  both 
specified,  then  these  are  used  to  authenticate  to  the  foreign  host;  otherwise  the  environment  and 
then  the  user’s  .netre  file  in  his  home  directory  are  searched  for  appropriate  information.  If  all 
this  fails,  the  user  is  prompted  for  the  information. 

The  port  inport  specifies  which  well-known  DARPA  Internet  port  to  use  for  the  connection;  it  will 
normally  be  the  value  returned  from  the  call  “getscrvbyname(”exec",  ’’tcp”)”  (see 
pe<seruenf(3N)).  The  protocol  for  connection  is  described  in  detail  in  r«ecd(8C). 

If  the  call  succeeds,  a  socket  of  type  SOCK_STREAM  is  returned  to  the  caller,  and  given  to  the 
remote  command  as  stdln  and  atdout.  If  Jd£p  is  non-zero,  then  a  auxiliary  channel  to  a  control 
process  will  be  setup,  and  a  descriptor  for  it  will  be  placed  in  *fdSp,  The  control  process  will 
return  diagnostic  output  from  the  command  (unit  2)  on  this  channel,  and  will  also  accept  bytes  on 
this  channel  as  being  UNIX  signal  numbers,  to  be  forwarded  to  the  process  group  of  the  com¬ 
mand.  If  fdSp  is  0,  then  the  stderr  (unit  2  of  the  remote  command)  will  be  made  the  same  as  the 
atdout  and  no  provision  is  made  for  sending  arbitrary  signals  to  the  remote  process,  although  you 
may  be  able  to  get  its  attention  by  using  out-of-band  data. 

SEE  ALSO 

rcmd(3N),  rexecd(8C) 

BUGS 

There  is  no  way  to  specify  options  to  the  toeket  call  which  rcxce  makes. 
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INTRO  (3S) 


STANDARD  I/O  LIBRARY 


INTRO  (3S) 


NAME 

stdio  -  standard  buffered  input/output  package 

SYNOPSIS 

#Inelude  <ttdIo.h> 

FILE  *stdln} 

FILE  *stdout| 

FILE  *atderr} 

DESCRIPTION 

The  functions  described  in  section  3S  constitute  a  user-level  buffering  scheme.  The  in-line  macros 
gete  and  pu(e(3S)  handle  characters  quickly.  The  higher  level  routines  get»,  fgeta,  eeanf,  facanf, 
/read,  pute,  fpute,  print/,  /print/,  /write  all  use  getc  and  pule;  they  can  be  freely  intermixed. 

A  file  with  associated  buffering  is  called  a  atream,  and  is  declared  to  be  a  pointer  to  a  defined  type 
FILE.  A  /«pen(3S)  creates  certain  descriptive  data  for  a  stream  and  returns  a  pointer  to  desig¬ 
nate  the  stream  in  all  further  transactions.  There  are  three  normally  open  streams  with  constant 
pointers  declared  in  the  include  file  and  associated  with  the  standard  open  files: 

stdln  standard  input  file 

atdout  standard  output  file 

■tderr  standard  error  file 

A  constant  ‘pointer’  NULL  (0)  designates  no  stream  at  all. 

An  integer  constant  EOF  (-1)  is  returned  upon  end  of  file  or  error  by  integer  functions  that  deal 
with  streams. 

Any  routine  that  uses  the  standard  input/output  package  must  include  the  header  file  <atdio.k> 
of  pertinent  macro  definitions.  The  functions  and  constants  mentioned  in  sections  labeled  3S  are 
declared  in  the  include  file  and  need  no  further  declaration.  The  constants,  and  the  following 
‘functions*  are  implemented  as  macros;  redeclaration  of  these  names  is  perilous:  gete,  getchar, 
pute,  putehar,  /eo/,  /error,  /Ueno,  elrerr. 

SEE  ALSO 

open(2),  cIose(2),  read(2),  write(2),  fread(3S),  f8eek(3S) 

DIAGNOSTICS 

The  value  EOF  is  returned  uniformly  to  indicate  that  a  FILE  pointer  has  not  been  initialized 
with  /open,  input  (output)  has  been  attempted  on  an  output  (input)  stream,  or  a  FILE  pointer 
designates  corrupt  or  otherwise  unintelligible  PILE  data. 

For  purposes  of  efficiency,  this  implementation  of  the  standard  library  has  been  changed  to  line 
buffer  output  to  a  terminal  by  default  and  attempts  to  do  this  transparently  by  flushing  the  out¬ 
put  whenever  a  read(2)  from  the  standard  input  is  necessary.  This  is  almost  always  transparent, 
but  cause  confusion  or  malfunctioning  of  programs  which  use  standard  i/o  routines  but  use 
read(2)  themselves  to  read  from  the  standard  input. 

In  cases  where  a  large  amount  of  computation  is  done  after  printing  part  of  a  line  on  an  output 
terminal,  it  is  necessary  to  ffluah  (see  /close(3S))  the  standard  output  before  going  off  and  compufc. 
ing  so  that  the  output  will  appear. 

BUGS 

The  standard  buffered  functions  do  not  interact  well  with  certain  other  library  and  system  func¬ 
tions,  especially  v/ork  and  abort. 

LIST  OP  FUNCTIONS 

Name  Appeara  on  Page  Deaeription 

clearerr  ferror.3s  stream  status  inquiries 

fclose  fclose.3s  close  or  flush  a  stream 

fdopen  fopen.Ss  open  a  stream 
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feof 

ferror  .3s 

Stream  status  inquiries 

ferror 

ferror.Ss 

stream  status  inquiries 

fflush 

fcIose.Ss 

close  or  flush  a  stream 

fgetc 

getc.38 

get  character  or  integer  from  stream 

fgets 

gets.38 

get  a  string  from  a  stream 

fileno 

ferror.38 

stream  status  inquiries 

fopen 

fopen.Ss 

open  a  stream 

fpriQtf 

printf.Ss 

formatted  output  conversion 

fputc 

putc.Ss 

put  character  or  word  on  a  stream 

fputs 

puts.3s 

put  a  string  on  a  stream 

fread 

fread. 38 

buffered  binaiy  input/output 

f  reopen 

fopen.38 

open  a  stream 

fscanf 

scanf  .38 

formatted  input  conversion 

fseek 

f8eek.3s 

reposition  a  stream 

rieii 

fseek.Ss 

reposition  a  stream 

fwrite 

fread  .38 

buffered  binary  input/output 

getc 

getc.Ss 

get  character  or  integer  from  stream 

getchar 

getc.Ss 

get  character  or  integer  from  stream 

gets 

getB.38 

get  a  string  from  a  stream 

getw 

gete.Sa 

get  character  or  integer  from  stream 

pciose 

popen.Ss 

initiate  I/O  to/from  a  process 

popen 

popen.38 

initiate  I/O  to/from  a  process 

printf 

printf.Ss 

formatted  output  conversion 

putt 

putc.Ss 

put  character  or  word  on  a  stream 

putchar 

putc.Ss 

put  character  or  word  on  a  stream 

puts 

put8.38 

put  a  string  on  a  stream 

putw 

putc.Ss 

put  character  or  word  on  a  stream 

rewind 

heek.38 

reposition  a  stream 

scanf 

8canf.3s 

formatted  input  conversion 

setbuf 

setbuLSs 

assign  buffering  to  a  stream 

setbuffer 

setbuf.Ss 

assign  buffering  to  a  stream 

setlinebuf 

setbuf.Ss 

assign  buffering  to  a  stream 

sprintf 

printf.Ss 

formatted  output  conversion 

sscanf 

scanf.Ss 

formatted  input  conversion 

stdio 

intro.38 

standard  buffered  input/output  package 

uDgete 

ungetc.Ss 

push  character  back  into  input  stream 
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NAME 

fclose,  filttsb  -  close  or  flush  a  stream 

SYNOPSIS 

#lnelude  <Btdlodi> 

fcIose(8tream) 

FILE  *siream{ 

£nu8h(8tream) 

FILE  *fltreanif 

DESCRIPTION 

Fclose  causes  any  buffers  for  the  named  stream  to  be  emptied,  and  the  file  to  be  closed.  Buffers 
allocated  by  the  standard  input/output  system  are  freed. 

Fclose  is  performed  automatically  upon  calling  e»t(3). 

FJlush  causes  any  buffered  data  for  the  named  output  stream  to  be  written  to  that  file.  The 
stream  remains  open. 

SEE  ALSO 

close(2),  fopen(3S),  8etbuf(3S) 

DIAGNOSTICS 

These  routines  return  EOF  if  stream  is  not  associated  with  an  output  file,  or  if  buffered  data  can¬ 
not  be  transferred  to  that  file. 
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NAME 

fenor,  feof,  clearerr,  fileno  -  Btream  status  inquiries 

SYNOPSIS 

#Inelude  <stdlo.h> 

feof(stream) 

FILE  ^streamt 

ferror(8tream) 

FILE  ’‘‘stream 

elesurerr(stream) 

FILE  ^stream 

flleno(stream) 

FILE  *stream| 

DESCRIPTION 

Feof  returns  non-zero  when  end  of  Sle  is  read  on  the  named  input  eiream,  otherwise  zero. 

Ferror  returns  non-zero  when  an  error  has  occurred  reading  or  writing  the  named  etream,  other* 
wise  zero.  Unless  cleared  by  clearerr,  the  error  indication  lasts  until  the  stream  is  closed. 

Clrerr  resets  the  error  indication  on  the  named  etream. 

Fileno  returns  the  integer  file  descriptor  associated  with  the  etream,  see  open{2). 

These  functions  are  implemented  as  macros;  they  cannot  be  redeclared. 

SEE  ALSO 

fopen(3S),  open(2) 
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NAME 

fopen,  freopen,  fdopen  -  open  a  stream 

SYNOPSIS 

#lnelud«  <stdio.h> 

FILE  *fopen(fiIenamef  type) 
char  *fllename,  '''typei 

FILE  *freopeii(fllenaittef  type,  ctream) 
char  ^filename,  *type| 

FILE  ^streami 

FILE  *fdopen(flIdee,  type) 
char  *typet 

DESCRIPTION 

Fopen  opens  the  file  named  by  filename  and  associates  a  stream  with  it.  Fopen  returns  a  pointer 
to  be  used  to  identify  the  stream  in  subsequent  operations. 

Type  is  a  character  string  having  one  of  the  following  values; 

’’r*  open  for  reading 
"w"  create  for  writing 

"a”  append:  open  for  writing  at  end  of  file,  or  create  for  writing 

In  addition,  each  type  may  be  followed  by  a  ’+  ’  to  have  the  file  opened  for  reading  and  writing, 
"rd-  ”  positions  the  stream  at  the  beginning  of  the  file,  "w^  ”  creates  or  truncates  it,  and  ”a+  ” 
positions  it  at  the  end.  Both  reads  and  writes  may  be  used  on  read/write  streams,  with  the  tirni* 
tation  that  an  feeek,  rewtni,  or  reading  an  end^oMle  must  be  used  between  a  read  and  a  write  or 
vice-versa. 

Freopen  substitutes  the  named  file  in  place  of  the  open  etream.  It  returns  the  original  value  of 
tiream.  The  original  stream  is  closed. 

Freopen  is  typically  used  to  attach  the  preopened  constant  names,  stdln,  atdout,  stderr,  to 
specified  files. 

Fdopen  associates  a  stream  with  a  file  descriptor  obtained  from  open,  dup,  ereat,  or  pipe{2).  The 
type  of  the  stream  must  agree  with  the  mode  of  the  open  file. 

SEE  ALSO 

open(2),  fclose(3S) 

DIAGNOSTICS 

Fopen  and  freopen  return  the  pointer  NULL  if  filename  cannot  be  accessed. 

BUGS 

Fdopen  is  not  portable  to  systems  other  than  UNIX. 

The  read/write  typee  do  not  exist  on  all  systems.  Those  systems  without  read/write  modes  will 
probably  treat  the  type  as  if  the  ’  was  not  present.  These  are  unreliable  in  any  event. 


Sun  Release  1.1 


Last  change:  9  June  1981 


5 


FREAD  ( 3S )  STANDARD  1/0  LBRARY  PREAD  ( 3S  ) 


NAME 

fread,  fwrite  -  buffeted  binary  input/output 

SYNOPSIS 

^Includ*  <atdloJi> 

flread(ptr,  •lzeof(*ptr)t  nltemn,  ntresm) 

FHyE  *ntream{ 

fwrlte(ptrt  ■lxeof(*ptr),  nltenut  ntrnam) 

FILE  ’"streami 

DESCRIPTION 

Fread  reads,  into  a  block  beginning  at  ptr,  niteme  of  data  of  the  type  of  *ptr  from  the  named 
input  etream.  It  returns  the  number  of  items  actually  read. 

If  etream  is  ntdln  and  the  standard  output  is  line  buffered,  then  any  partial  output  line  will  be 
flushed  before  any  call  to  read{2)  to  satisiy  the  fread. 

Fwrite  appends  at  most  niteme  of  data  of  the  type  of  *ptr  beginning  at  ptr  to  the  named  output 
etream.  It  returns  the  number  of  items  actually  written. 

SEE  ALSO 

read(2),  write(2),  fopen(3S),  getc(3S),  putc(3S),  get8(3S),  put8(3S),  printf(3S),  scanf(3S) 
DIAGNOSTICS 

Fread  and  fwrite  return  0  upon  end  of  flie  or  error. 
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NAME 

fseek,  ftell,  rewind  -  reposition  a  stream 

SYNOPSIS 

#lnelud«  <itdlo.b> 

fBeek(8tream,  offset^  ptrname) 

FILE  *Btreun{ 
long  offseti 

long  ftell(streani) 

FILE  *streain| 

rewlnd(8tresm) 

DESCRIPTION 

Fattk  sets  the  position  of  the  next  input  or  output  operation  on  the  itrtam.  The  new  position  is 
at  the  signed  distance  off$ei  bytes  from  the  beginning,  the  current  position,  or  the  end  of  the  file, 
according  as  ptrname  has  the  value  0, 1,  or  2. 

Feeek  undoes  any  effects  of  uni;etc(3S). 

Ftell  returns  the  current  value  of  the  offset  relative  to  the  beginning  of  the  file  associated  with  the 
named  elream.  It  is  measured  in  bytes  on  UNIX;  on  some  other  systems  it  is  a  magic  cookie,  and 
the  only  foolproof  way  to  obtain  an  offset  for  fseek. 

Rewind{etream)  is  equivalent  to  fseek(stream,  OL,  0). 

SEE  ALSO 

lseek(2),  fopen(3S) 

DIAGNOSTICS 

Fseek  returns  -1  for  improper  seeks. 
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NAME 

getc,  getchar,  fgetc,  getw  -  get  character  ot  integer  from  stream 

SYNOPSIS 

#include  <Bt<lloJi> 

tnt  gete(8tream) 

FILE  ^stream; 

Int  getebarO 

Int  f^etc(streain)^ 

FILE  *Btream| 

tnf  getw(stream) 

FILE  *stream| 

DESCRIPTION 

Gele^rettmis  the  next  character  from  the  named  input  etreantr 
Getckari)  is  id«itical  to  getc{9(din)^ 

Fgete  behaves  like  gete,  but  is  a  grauine  function,  not  a.  macro;  it  may  be  used  to  save  objKt 
text. 

Getw  returns  the  next  CInt  (woFdHrom.  the- nmned  input  etream.  It  returns  the  constant-EOF 
upon  end  of  file  or  error,  but  since  that  is  a  good  integer  value,  /eo/and./crrer(3S)  should  Ee  used 
to  check  the  success  of  getw.  (jefarassumes  no  special  .alignment  m  the  file. 

SEE  ALSO 

fopen(3S),  putc(3S)rget8(3S),  seanf(3S),  flread(^),  ungetc(3S) 

DIAGNOSTICS 

These- tanctt<uis  return  the  integer  coB8taat~EOF  at  end  of  file  or  upon  read  error. 

A  stop  with  message,  ‘Reading  bad  fits’,  means  an  atten^t  has  been  made  to  read  from  a  stream 
that  has  not  been  opened  for  reading  by  ftpen. 

BUGS 

The  end-of-file  return  from  getehar  is  incompatible  with  that  in  UNIX  editions  i>fi. 

Because  it  is  implemented  as  a  macro,  getc  toeats  a  etream  argument  with  side  effects  incorrectly. 
In  particular,  ‘getc('*f+  + );’  doesn’t-work  sensibly. 

Data  files  written  and  read  with  ptttw  and  getw  are  not  portable;  the  size  of  an  Int  and  the  order 
in  which  data  bytes  are  stored  within  an  Int  varies  between  machines. 
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NAME 

gets,  fgets  -  get  a  string  from  a  stream 

SYNOPSIS 

#lnelude  <8tdlo.h> 

char  *getB(8) 
char  *8| 

char  *'fgett(t»  n,  stream) 
char  *s| 

FILE  *strearo| 

DESCRIPTION 

Gett  reads  a  string  into  $  from  the  standard  input  stream  stdin.  The  string  is  terminated  by  a 
newline  character,  which  is  replaced  in  «  by  a  null  character.  Gets  returns  its  argument. 

Fgeta  reads  n-1  characters,  or  up  to  a  newline  character,  whichever  comes  first,  from  the  stream 
into  the  string  s.  The  last  character  read  into  s  is  followed  by  a  null  character.  Fgets  returns  its 
first  argument. 

SEE  ALSO 

put8(3S),  getc(3S),  scanf(3S),  fread(3S),  ferror(3S) 

DIAGNOSTICS 

Gets  and  fgets  return  the  constant  pointer  NULL  upon  end  of  file  or  error. 

BUGS 

Gets  deletes  a  newline,  fgets  keeps  it,  all  in  the  name  of  backward  compatibility. 
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P0PEN(3S) 


STANDARD  I/O  LffiRARY 


NAME 

popen,  pclose  -  initiate  I/O  to/from  a  process 

SYNOPSIS  ^ 

#lnelude  <std!o.h> 

FILE  *popen(coinmandt  typ^ 
ehsr  *coiBmatid»  *typ^ 

pclo>e(stream) 

FILE  *itr«un| 

DESCRIPTION 

The  arguments  to  poptn  are  pointers  to  miU-terminatcd  strings  containing  respectively  a  shell 
command  line  and  an  I/O  mode,  either  ’’r”  for  reading  or  for  writing.  It  creates  a  pipe 
between  the  calling  process  and  the  command  to  be  executed.  The  value  returned  is  a  stream 
pointer  that  can  be  used  (as  appropriate)  to  write  tnthe  standard  input  of  the  command  or  read 
from  its  standard  output. 

A  stream  opened  by  papen  should  be  closed  by  pclosr.  which- wafts  for  the  associated  process  to 
termmate  and  returns  the  exit  statuaof  the  command. 

Because  open  files  are  shared,  a  type  comman<rm3y  be  used^to  filter  ttdtn,  and  a  type  "w”  to 
filter  stdsui.-. 

SEEAESa 

pipe(2},  fopen(3S),  fclose(3S),  8y8tem(3),  wait(2),  6h(^ 

DIAGNOSTICS 

Popen  returns  a  null  pointer  if  files  or  processes  cannot  be  created,  or  the  shell  cannot  be 
accessed. 

Peloee  returns  -1  if  otream  is  not  associated  with  a  ‘pop.ened*'c(»ninand. 

BUGS 

Buffered  reading  before  opening  an  input  filter  may  leave  the  standard  input  of  that  filter  misposi* 
tioned.  Similar  problems  with  an  output  filter  may  be  fdrestaUed  by  careful  buffer  fiushing,  for 
instance,  with  ffiueh,  see  /cIo»e(3S). 

Popen  always  calls  «k,  never  calls  celt. 
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NAME 

printf,  fprintf,  sprintf  -  formatted  output  eonversion 

SYNOPSIS 

#Inelud«  <BtdloJ)> 

prIntf(forniat  arg  |  ...  ) 
ehfir 

fl>rlctf(8tream,  format  {,  arg  ]  ...  ) 

PILE  *fltream| 
ehar  '*format| 

8prlntf(o,  format  (»  arg  ] ...  ) 
ehar  %  format) 

#Inela<Ie  <vararg8Ji> 

_doprnt(format«  arg8»  stream) 
ehar  ^format) 
vaJUot  *arg8) 

FILE  ^stream) 

DESCRIPTION 

Print/  places  output  on  the  standard  output  stream  stdout.  Fprintf  places  output  on  the  named 
output  stream.  Sprint/  places  ‘output’  in  the  string  s,  followed  by  the  character  ‘\0’.  All  of  these 
routines  work  by  calling  the  implementation-dependent  routine  _doprnt,  using  the  variable-length 
argument  facilities  of  vararg8{3). 

Each  of  these  functions  converts,  formats,  and  prints  its  arguments  after  the  first  under  control  of 
the  first  argument.  The  first  argument  is  a  character  string  which  contains  two  types  of  objects: 
plain  characters,  which  are  simply  copied  to  the  output  stream,  and  conversion  specifications, 
each  of  which  causes  eonversion  and  printing  of  the  next  successive  arg 

Each  conversion  specification  is  introduced  by  the  character  %.  Following  the  %,  there  may  be 

•  an  optional  'minus  sign  which  specifies  le/t  adjustment  of  the  converted  value  in  the 
indicated  field; 

•  an  optional  digit  string  specifying  a  /ieid  width;  if  the  converted  value  has  fewer  charac¬ 
ters  than  the  field  width  it  will  be  blank-padded  on  the  left  (or  right,  if  the  left- 
adjustment  indicator  has  been  given)  to  make  up  the  field  width;  if  the  field  width  begins 
with  a  sero,  sero-padding  will  be  done  instead  of  blank-padding; 

•  an  optional  period  which  serves  to  separate  the  field  width  from  the  next  digit  string; 

•  an  optional  digit  string  specifying  a  precision  which  specifies  the  number  of  digits  to 
appear  after  the  decimal  point,  for  e-  and  f-conversion,  or  the  maximum  number  of  char¬ 
acters  to  be  printed  from  a  string; 

•  an  optional  *#’  character  specifying  that  the  value  should  be  converted  to  an  "alternate 
form".  For  e,  d,  s,  and  u,  conversions,  this  option  has  no  effect.  For  o  conversions,  the 
precision  of  the  number  is  increased  to  force  the  first  character  of  the  output  string  to  a 
sero.  For  x(X)  eonversion,  a  non-sero  result  has  the  string  Ox(OX)  prepended  to  it.  For 
e,  B,  f,  g,  and  6,  conversions,  the  result  will  always  contain  a  decimal  point,  even  if  no 
digits  follow  the  point  (normally,  a  decimal  point  only  appears  in  the  results  of  those 
conversions  if  a  digit  follows  the  decimal  point).  For  g  and  6  conversions,  trailing  zeros 
are  not  removed  from  the  result  as  they  would  otherwbe  be. 

•  the  character  1  specifying  that  a  following  d,  o,  x,  or  u  corresponds  to  a  long  integer  arg. 

•  .  a  character  which  indicates  the  type  of  conversion  to  be  applied. 
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A  field  width  or  precision  may  be  *•*  instead  of  a  digit  string.  In  this  case  an  integer  arg  supplies 
the  field  width  or  precision. 

The  conversion  characters  and  their  meanings  are 

dox  The  integer  arg  is  converted  to  decimal,  octal,  or  hexadecimal  notation  respectively. 

f  The  float  or  double  arg  is  converted  to  decimal  notation  in  the  style  ‘[*>]ddd.ddd’  where 

the  number  of  d’s  after  the  decimal  point  is  equal  to  the  precision  specification  for  the 
argument.  If  the  precision  is  missing,  6  digits  are  given;  if  the  precision  is  explicitly  0,  no 
digits  and  no  decimal  point  are  printed. 

«  The  float  or  double  arg  is  converted  in  the  style  ‘[>)d.ddde±  dd’  where  there  is  one  digit 
before  the  decimal  point  and  the  number  after  is  equal  to  the  precision  specification  for 
the  argument;  vriien  the  precision  in  missing,  6  digits  are  produced. 

g  The  float  or  double  arg  is  printed  in  style  d,  in  style  f,  or  in  style  e,  whichever  gives  full 
prec&ion  in  mtnnnum  space. 

The  %«,  %t,  and  %g  formats  prfnt  lE^  indeterminate  values  (infimty  or  not-apnumber)  as 
“Infinity”  or  “Nan”  respectively. 

e  The  character  arg  is  printed. 

•  Arg  is  taken  to  be  a  string  (character  pointer)  and  characters  from  the  string  are  printed 
until  a  null  character  or  until  the  number  of  characters  indicated  by  the  precision 
specification  is  reached;  however  if  the  precision  is  0  or  missing  all  characters  op  to  a  null 
are  printed. 

o  The  unsigned  integer  arg  is  converted  to  decimal  and  printed  (the  result  will  be  in  the 
range  0  through  MAXUINT,  where  MAXUINT  equals  4294967295  on  a  VAX-11  or  Sun 
and  65636  on  a  PDP-11). 

%  Print  a  no  argument  is  converted. 

In  no  case  does  a  non-existent  or  small  field  width  cause  truncation  of  a  field;  padding  takes  place 
only  if  the  specified  field  width  exceeds  the  actual  width.  Characters  generated  by  printj  are 
printed  by  pulc(3S). 

Examples 

To  print  a  date  and  time  in  the  form  ‘Sunday,  July  3,  10:02’,  where  weekday  and  month  are 
pointers  to  null-terminated  strings:- 

printf(’’%s,  %s  %d,  %02d;%02d’’,  weekday,  month,  day,  hour,  min); 

To  print  x  io  &  decimals; 

printf(’’pi  ^  4*atan(1.0)); 

SEE  ALSO 

putc(3S),  scanf(3S),.ecvt(3) 

BUGS 

Very  wide  fields  (>123  characters)  faQ. 

The  values  “Infi^nity"  and  “Nan”  cannot  be  read  scan/(3S). 
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NAME 

putc,  putchar,  fputc,  putw  -  put  character  or  word  on  a  stream 

SYNOPSIS 

#lnelud«  <ttdlo.h> 

Int  pute(e,  stream) 
char  e| 

FILE  Stream} 
putehar(e) 

f^ute(e»  stream) 

FILE  Stream) 

putw(wt  stream) 

FILE  Stream) 

DESCRIPTION 

Pule  api>endB  the  character  e  to  the  named  output  etream.  It  returns  the  character  written. 
Putchsr{e)  is  defined  as  puie{e,  stdout). 

Fputc  behaves  like  pute,  but  is  a  genuine  function  rather  than  a  macro. 

Putw  appends  C  lot  (word)  w  to  the  output  etream.  It  returns  the  integer  written.  Putw  neither 
assumes  nor  causes  special  alignment  in  the  file. 

ALrSO 

fopen(3S),  fclo8e(3S),  getc(3S),  puts(3S),  printf(3S),  fread(3S) 

DIAGNOSTICS 

These  functions  return  the  constant  EOF  upon  error.  Since  this  is  a  good  integer,  /error(3S) 
should  be  used  to  detect  putw  errors. 

BUGS 

Because  it  is  implemented  as  a  macro,  putc  treats  a  etream  argument  with  side  effects  improperly. 
In  particular  "putc(c,  *f+  + )”  doesn’t  work  sensibly. 

Errors  can  occur  long  after  the  call  to  putc. 

Data  files  written  and  read  with  putw  and  petw  are  not  portable;  the  size  of  an  Int  and  the  order 
in  which  data  bytes  are  stored  within  an  Int  varies  between  machines. 
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NAME 

puts,  fputs  -  put  a  string  on  a  stream 

SYNOPSIS 

#Iiieluda  <stdlo.h> 

put>(B) 
char  *■! 

fk>uts(S|  stream) 
char  ^ai 
FILE  *stream| 

DESCRIPTION 

Pvit  copies  the  nulLterminated  string  $  to  the  standard  output  stream  atdout  and  appends  a 
newline  character. 

Fputf  copies  the  null-terminated  string  » to  the  named  output  slresm. 

Neither  routine  copies  the  terminal  null  character. 

SEE  ALSO 

fopen(3S),  get8(3S),  putc(3S),  printr(3S),  rerror(3S) 
fread(3S)  for  /write 

BUGS 

PuU  appends  a  newline,  fputa  does  not,  all  in  the  name  of  backward  compatibility. 
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NAME 

8caiif«  fscanf,  sscanf  —  formatted  input  conversion 

SYNOPSIS 

#lnelude  <ttdlo.h> 

seanf(format  ( ,  pointer  1 . .  •  ) 
char  *forinat| 

fBeanf(ntreaini  format  ( ,  pointer  )  •  •  •  ) 

FILE  *ntream| 
char  ^format) 

8scanf(B»  format  [ ,  pointer  ]  . . .  ) 
char  *B,  *formatt 

DESCRIPTION 

Seanf  reads  from  the  standard  input  stream  atdln.  Fscanf  reads  from  the  named  input  $tream. 
Steanf  reads  from  the  character  string  s.  Eaich  function  reads  characters,  interprets  them  accord¬ 
ing  to  a  format,  and  stores  the  results  in  its  arguments.  Each  expects  as  arguments  a  control 
string  format,  described  below,  and  a  set  of  pointer  arguments  indicating  where  the  converted  in¬ 
put  should  be  stored. 

The  control  string  usually  contains  conversion  specifications,  which  are  used  to  direct  interpretap 
tion  of  input  sequences.  The  control  string  may  contain: 

1.  Blanks,  tabs  or  newlines,  which  match  optional  white  space  in  the  input. 

2.  An  ordinary  character  (not  %)  which  must  match  the  next  character  of  the  input  stream. 

3.  Conversion  specifications,  consisting  of  the  character  %,  an  optional  assignment  suppressing 
character  *,  an  optional  numerical  maximum  field  width,  and  a  conversion  character. 

A  conversion  specification  directs  the  conversion  of  the  next  input  field;  the  result  is  placed  in  the 
variable  pointed  to  by  the  corresponding  argument,  unless  assignment  suppression  was  indicated 
by  An  input  field  is  defined  as  a  string  of  non-space  characters;  it  extends  to  the  next  inap¬ 
propriate  character  or  until  the  field  width,  if  specified,  is  exhausted. 

The  conversion  character  indicates  the  interpretation  of  the  input  field;  the  corresponding  pointer 
argument  must  usually  be  of  a  restricted  type.  The  following  conversion  characters  are  legal; 

%  a  single  '%’  is  expected  in  the  input  at  this  point;  no  assignment  is  done, 
d  a  decimal  integer  is  expected;  the  corresponding  argument  should  be  an  integer  pointer, 
o  an  octal  integer  is  expected;  the  corresponding  argument  should  be  a  integer  pointer. 

X  a  hexadecimal  integer  is  expected;  the  corresponding  argument  should  be  an  integer  pointer. 

B  a  character  string  is  expected;  the  corresponding  argument  should  be  a  character  pointer 

pointing  to  an  array  of  characters  large  enough  to  accept  the  string  and  a  terminating  ‘\0’, 
which  will  be  added.  The  input  field  is  terminated  by^  a  space  character  or  a  newline. 

c  a  character  is  expected;  the  corresponding  argument  should  be  a  character  pointer.  The  nor¬ 
mal  skip  over  space  characters  is  suppressed  in  this  case;  to  read  the  next  non-space  charac¬ 
ter,  try  '%l8'.  If  a  field  width  is  given,  the  corresponding  argument  should  refer  to  a  charac¬ 
ter  array,  and  the  indicated  number  of  characters  is  read. 

e  a  floating  point  number  is  expected;  the  next  field  is  converted  accordingly  and  stored 

f  through  the  corresponding  argument,  which  should  be  a  pointer  to  a  float.  The  input  format 

for  floating  point  numbers  is  an  optionally  signed  string  of  digits  possibly  containing  a  de¬ 
cimal  point,  followed  by  an  optional  exponent  field  consisting  of  an  E  or  e  followed  by  an  op¬ 
tionally  signed  integer. 

[  indicates  a  string  not  to  be  delimited  by  space  characters.  The  left  bracket  is  followed  by  a 
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set  of  characters  and  a  right  bracket;  the  characters  between  the  brackets  define  a  set  of 
characters  making  up  the  string.  If  the  first  character  is  not  circumflex  ( ' ),  the  input  field  is 
all  characters  until  the  first  character  not  in  the  set  between  the  brackets;  if  the  first  charac¬ 
ter  after  the  left  bracket  is  the  input  field  is  ail  characters  until  the  first  character  which  is 
in  the  remaining  set  of  characters  between  the  brackets.  The  corresponding  argument  must 
point  to  a  character  array. 

The  conversion  characters  d,  o  and  x  may  be  capitalized  or  preceded  by  I  to  indicate  that  a 
pointer  to  long  rather  than  to  lot  is  in  the  argument  list.  Similarly,  the  conversion  characters  • 
or  f  ms^  be  capitalized  or  preceded  by  1  to  indicate  a  pointer  to  double  rather  than  to  float. 
The  conversion  characters  d,  o  and  x  may  be  preceded  by  h  to  indicate  a  pointer  to  short  rather 
than  to  Int. 

The  tcanf  functions  return  the  number  of  suecessfhlly  matched  and  assigned  input  items.  This 
can  be  used  to  decide  how  many  input  items  were  found.  The  constant  EOF  is  returned  upon 
end  of  input;  note  that  this  is  different  from  0,  which  means  that  no  conversion  was  done;  if 
conversion  was  intended,  it  was  frustrated  by  an  inappropriate  character  in  the  input. 

For  example,  the  call 

mt  i;  float  xrebar  namejSO]; 
scanf^”%d%f%s”,  Sn,  &x,  name); 

with  the  input-  line 

25  54.32E-1  thompson 

will  assign  to  t  the  value  25,  z  the  value  5.432,  and  name  will  contain  'thompton\0’.  Or, 

int  i;  float  x;  char  name|60]; 

8canf(”%2d%f%*d%[1234Sfi78g0p,  £i,  tx,  name); 

with  input 

60780  0123  60a72 

will  assign  66  to  t,  789.0  to  x,  skip  ‘0123’,  and  place  the  string  '50\0’  in  name.  The  next  call  to 
setehar  will  return  ‘a’. 

SEE  ALSO 

atof(3),  getc(3S),  printf(3S) 

DIAGNOSTICS 

The  eeairf  functions  return  EOF  on  end  of  input,  and  a  short  count  for  missing  or  illegal  data 
items. 

BUGS 

The  success  of  literal  matches  and  suppressed  assignments  is  not  directly  determinable. 

Seanf  cannot  read  the  strings  which  prtnl/(3S)  generates  for  IEEE  indeterminate  floating  point 
values. 

Scan/ provides  no  way  to  convert  a  number  m  any  arbitrary  base  (decimal,  hex  or  octal)  based  on 
the  traditional  C  conventions  (leading  0  or  Ox). 
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NAME 

Betbuf,  setbuffer,  fletlinebuf  -  assign  buffering  to  a  stream 

SYNOPSIS 

#lnelude  <etdlo.h> 

•etbttf(stream,  buf) 

FILE 

ehnr  *buf{ 

setbufl’er(Btreaint  buf»  else) 

FILE  "‘•treami 
char  *buf| 

Int  else} 

setUnebuf(8treani) 

FILE  ^stream} 

DESCRIPTION 

The  three  types  of  buffering  available  are  unbuffered,  block  buffered,  and  line  buffered.  When  an 
output  stream  is  unbuffered,  information  appears  on  the  destination  file  or  terminal  as  soon  as 
written;  when  it  is  block  buffered  many  characters  are  saved  up  and  written  as  a  block;  when  it  is 
line  buffered  characters  are  saved  up  until  a  newline  is  encountered  or  input  is  read  from  stdin. 
Ffinah  (see  fcloae{iS))  may  be  used  to  force  the  block  out  early.  Normally  all  files  are  block 
buffered.  A  buffer  is  obtained  from  maffcc(3)  upon  the  first  gete  or  pu(c(3S)  on  the  file.  If  the 
standard  stream  etdout  refers  to  a  terminal  it  is  line  buffered.  If  the  standard  stream  etderr 
refers  to  a  terminal  it  is  line  buffered. 

Setbitfis  used  after  a  stream  has  been  opened  but  before  it  is  read  or  written.  The  character  ar* 
ray  buf  is  used  instead  of  an  automatically  allocated  buffer.  If  buf  is  the  constant  pointer  NULL, 
input/output  will  be  completely  unbuffered.  A  manifest  constant  BUFSIZ  tells  bow  big  an  array 
is  needed: 

char  buf[BUFSIZ]; 

Setbuffer,  an  alternate  form  of  aetbuf,  is  used  after  a  stream  has  been  opened  but  before  it  is  read 
or  written.  The  character  arr^  buf  whose  size  is  determined  by  the  size  argument  is  used  instead 
of  an  automatically  allocated  buffer.  If  buf  is  the  constant  pointer  NULL,  input/output  will  be 
completely  unbuffered. 

Setlinebuf  is  used  to  change  stdout  or  stderr  (only)  from  block  buffered  or  unbuffered  to  line 
buffered.  Unlike  setbufaad  setbuffer  it  can  be  used  at  any  time  that  the  file  descriptor  is  active. 

A  file  can  be  changed  from  unbuffered  or  line  buffered  to  block  buffered  by  using  freopen  (see 
/epeR(3S)).  A  file  can  be  changed  from  block  buffered  or  line  buffered  to  unbuffered  by  using  freo¬ 
pen  followed  by  se(6u/witb  a  buffer  argument  of  NULL. 

SEE  ALSO 

fopen(3S),  getc(3S),  putc(3S),  malIoc(3),  fclo8e(3S),  puts(3S),  printf(3S),  fread(3S) 
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NAME 

angetc  -  push  character  back  into  input  stream 

SYNOPSIS 

^Include  <6tdIo.h> 

ttnget<(e,  atpeam) 

FILE  *BtreMn| 

DESCRIPTION 

Uhgelc  pushes  the  character  e  back  on  an  input  stream.  That  character  wQI  be  returned  by  the 
next  gefc  call  on  that  stream..  Ungtte  returns  c. 

One  character  of  pushback  is  guaranteed  provided  something  has  been  read  from  the  stream  and 
the  stream  is  actually  buffered.  Attempts  to  push  EOF  are  rejected. 

An  /reelfSS)  erases  all  memory  of  pushed  back  characters. 

SEE  ALSO 

getc(3S),  setbuf(3S),  f8eek{3S) 

DIAGNOSTICS 

Vngetc  returns  EOF  if  It  can’t  push  a  character  back. 
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intro  -  introduction  to  other  libraries 
DESCRIPTION 

This  section  contains  manual  pages  describing  other  libraries,  which  are  available  only  from  C. 
The  list  below  includes  libraries  which  provide  device  independent  plotting  functions,  terminal 
independent  screen  management  routines  for  two  dimensional  non-bitmap  display  terminals,  and 
functions  for  managing  data  bases  with  inverted  indexes.  All  functions  are  located  in  separate 
libraries  indicated  in  each  manual  entry. 

FILES 

/usr/lib/libcurses.a 
/usr/lib/libdbm.a 
/usr/lib/libmp.a 
/usr/lib/libplot.a 
/usr/lib/lib300.a 
/usr/lib/lib300s.a 
/usr/lib/lib450.a 
/usr/lib/lib4014.a 
/usr/lib/libtermcap.a 
/usr/lib/libtenncap_p.a 
/usr/lib/libtermlib.a 
/usr/lib/libtermlib_p.a 


screen  management  routines  (see  curree(3x)) 
data  base  management  routines  (see  d&m(3x)) 
multiple  precision  math  library  (see  mp(3x)) 
plot  routines  (see  p/of(3x)) 

n 

n 

terminal  handling  routines  (see  <ermcap(3x)) 
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NAME 

curses  ~  screen  functions  with  “optimal”  cursor  motion 
SYNOPSIS 

ce  I  flags  )  files  -leurtua  -Itermeap  [  libraries  ) 

DESCRIPTION 

These  routines  give  the  user  a  method  of  updating  screens  with  reasonable  optimization.  They 
keep  an  image  of  the  current  screen,  and  the  user  sets  up  an  image  of  a  new  one.  Then  the 
refrethQ  tells  the  routines  to  make  the  current  screen  look  like  the  new  one.  In  order  to  initialize 
the  routines,  the  routine  initserO  must  be  called  before  any  of  the  other  routines  that  deal  with 
windows  and  screens  are  used.  The  routine  endwinQ  should  be  called  before  exiting. 

SEE  ALSO 

ioctl(2),  getenv(3},  tty(4),  termcap(&) 

FUNCTIONS 


addcb(ch) 

add  a  character  to  tidter 

add8tr(8tr) 

add  a  string  to  tldtct 

box(win,vert,hor) 

draw  a  box  around  a  window 

crmode() 

set  cbreak  mode 

clear() 

clear  ttdtcr 

cIearok(8cr,boolf) 

set  clear  flag  for  ter 

clrtobot() 

clear  to  bottom  on  ttdter 

cIrtoeolO 

clear  to  end  of  line  on  ttdter 

delchO 

delete  a  character 

deletebO 

delete  a  line 

delwin(win) 

delete  win 

echo() 

set  echo  mode 

endwinO 

end  window  modes 

eraseO 

erase  ttdter 

getch() 

get  a  char  through  ttdter 

getcap(name) 

get  terminal  capability  name 

getstr(str) 

get  a  string  through  ttdter 

gettmode() 

get  tty  modes 

getyx(win,y,x) 

get  (y,x)  co-ordinates 

inch() 

get  char  at  current  (y,x)  co-ordinates 

initscrO 

initialize  screens 

insch(c) 

insert  a  char 

insertlnO 

insert  a  line 

Ieaveok(win,boolf ) 

set  leave  flag  for  win 

longDame(termbuf,name) 

get  long  name  from  termbuf 

move(y,x) 

move  to  (y,x)  on  ttdter 

mvcttr(lasty,lastx,newy,newx) 

actually  move  cursor 

newwin(line8,col8,begin_y,begin_x) 

create  a  new  window 

nl() 

set  newline  mapping 

nocrmodeO 

unset  cbreak  mode 

noecho() 

unset  echo  mode 

nonl() 

unset  newline  mapping 

noraw() 

unset  raw  mode 

overlay  (win  l,win2) 

overlay  winl  on  win2 

overwrite(win  1  ,win2) 

overwrite  winl  on  top  of  win2 

printw(fmt,argl,arg2,...) 

printf  on  ttdter 

raw() 

set  raw  mode 

refreshO 

make  current  screen  look  like  ttdter 

resetty() 

reset  t(y  flags  to  stored  value 
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•avettyO 

•canw(fint,argl ,  arg2, .. .) 

scroll(win) 

scroUok(win,boolf) 

8etterm(Daine) 

8taDdead() 

■tandout() 

■ubwin(win, lines, cols, beginjr.beginjx) 

touchwin(win) 

unctrl(ch) 

waddch(win,ch) 

wadd8tr(win,str) 

wclear(win) 

wc]rtobot(wiB) 

wclrtoeol(wis) 

wdelch(win,c) 

wdeleteln(win) 

werase(win) 

wgetcb(wio) 

wget8tr(win,8tr) 

winch(win) 

win8cb(win,c) 

win8erttn(win) 

winove(win,y,x) 

wprintw(win,fmt,argl,arg2,...) 

wrefre8b(win) 

w8canw(wiD,fint,argl,arg2,...) 

w8tandend(wiD) 

'W8tandout(wm) 


stored  current  tty  flags 
scanf  through  etdacr 
scroll  win  one  line 
set  scroll  flag 

set  term  variables  for  name 
end  standout  mode 
start  standout  mode 
create  a  subwindow 
“change”  all  of  win 
printable  version  of  ch 
add  char  to  win 
add  string  to  win 
clear  win 

clear  to  bottom  of  win 
clear  to  end  of  line  on  win 
delete  char  from  win 
delete  line  from  unn 
erase  win 

get  a  char  through  win 

get  a  string  through  win 

get  char  at  current  (y,x)  in  win 

insert  char  into  win 

insert  line  into  win 

set  current  (y,x)  co-ordinates  on  win 

printf  on  win 

make  screen  look  like  win 

scanf  through  win 

end  standout  mode  on  win 

start  standout  mode  on  win 
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NAME 

dbminit,  fetch,  store,  delete,  firstkey,  sextkey  -  data  base  subroatiaes 

SYNOPSIS 

typedef  struct  { 

char  *dptr; 
tnt  dstse} 

}  datum} 

dbminlt(flle) 
char  ^fllc} 

datum  feteh(key) 
datum  kcyi 

store(key,  content) 
datum  key,  content} 

delete(key) 
datum  key} 

datum  flrstkcyO 

datum  nextkey(key) 
datum  key} 

DESCRIPTION 

These  functioas  maintain  key /content  pairs  in  a  data  base.  The  functions  will  handle  very  large 
(a  billion  blocks)  databases  and  will  access  a  keyed  item  in  one  or  two  file  system  accesses.  The 
functions  are  obtained  with  the  loader  option  -Idbm. 

Kelts  and  contents  are  described  by  the  datum  typedef.  A  datum  specifies  a  string  of  dstse  bytes 
pointed  to  by  dptr.  Arbitraiy  binary  data,  as  well  as  normal  ASCII  strings,  are  allowed.  The  data 
base  is  stored  in  two  files.  One  file  is  a  directory  containing  a. bit  map  and  has  '.dir*  as  its  suffix. 
The  second  file  contains  all  data  and  has  *4>ag’  as  its  suffix. 

Before  a  database  can  be  accessed,  it  most  be  opened  by  dbminit.  At  the  time  of  this  call,  the  files 
^e.dlr  and  ^e.pag  must  exist.  (An  empty  database  is  created  by  creating  cero-Iengtb  '.dir*  and 
'.pag'  filesO 

Once  open,  tbe  data  stored  under  a  key  u  accessed  by  fetch  and  data  is  placed  under  a  key  by 
etore.  A  key  (and  its  associated  contents)  is  deleted  by  delete.  A  linear  pass  through  all  keys  in  a 
database  may  be  made,  in  an  (apparently)  random  order,  by  use  of  firetkey  and  nextkey.  Firetkey 
wHI  return  the  first  key  in  the  database.  With  any  key  nextkey  will  return  tbe  next  key  in  the 
database.  This  code  will  traverse  the  data,  base: 

for  (key  —  firstkey();.  key  .dptr  I"  NULL;  key  —  nextkey(key)) 

DIAGNOSTICS 

All  functions  that  return  an  ini  indicate  errors  with  negative  values.  A  zero  return  indicates  ok. 
Routines  that  return  a  datum  indicate  errors  with  a  null  (0)  dptr. 

BUGS 

The  '.pag*  file  will  contain  holes  so  that  its  apparent  size  is  about  four  times  Its  actual  content. 
Older  UNIX  systems  may  create  real  file  blocks  for  these  holes  when  touched.  These  files  cannot 
be  copied  by  normal  means  (cp,  cat,  tp,  tar,  ar)  without  filling  in  the  holes. 

Dptr  pointers  returned  by  these  subroutines  i>oint  into  static  storage  that  is  changed  by  subse¬ 
quent  calls. 

The  sum  of  the  sizes  of  a  key /content  pair  must  not  exceed  the  internal  block  size  (currently  1024 
bytes).  Moreover  all  key /content  pairs  that  hash  together  must  fit  on  a  single  block.  Store  will 
return  an  error  in  the  event  that  a  disk  block  fills  with  inseparable  data. 
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Delete  does  not  physically  reclaim  file  space,  although  it  does  make  it  available  for  reuse. 

The  order  of  keys  presented  by  firstkey  and  nextkey  depends  on  a  hashing  function,  not  on  any> 
thing  interesting. 

There  are  no  interlocks  and  no  provisionunreliable  cache  flushing;  thus  concurrent  updating  and 
reading  is  risky. 
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NAME 

itom,  madd,  msub,  mult,  mdlv,  min,  mout,  pow,  gcd,  rpow  -  multiple  precision  integer  arithmetic 

SYNOPSIS 

#inelude  <inp.h> 

madd(a,  b,  e) 

MINT  *•,  *b,  *ct 

m8ub(st  b|  c) 

MINT  *•,  ‘b,  *<51 

mult(a,  b-f  e) 

MINT  ♦a,  *b,  *ct 

indlv(a,  brq»  r) 

MINT  *a,-*b,  *q» 

mlti(a) 

MINT*at 

niout(a) 

MINT*a| 

pow(a,  b,  e,  d) 

MINT*a,  *b,  %  *dr 

ged(a,  b,  e) 

MINT  *a,  •b,  *c| 

rpow(a,  n,  b) 

MINT  *a,  *bi 
short  Di 

m8qrt(a,  b,  r) 

MINT  •a,  ‘b,  ♦ri 

sdlv(a,  n,  q,  r) 

MINT  *a,  *q| 
short  n,  *r| 

MINT  *itom(ii)^ 
short  nr 

DESCRIPTION 

These  routines  perform  arithmetic  on  integers  of  arbitrary  length.  The  integers  are  stored  iminfl 
the  defined  type  MINT.  Pointers  to  a  MINT  should  be  initialized  using  the  function  itom,  which 
sets  the  initial  value  to  n.  After  that  space  is  managed  automatically  by  the  routines. 

Madd,  msub  and  mult  assign  to  their  third  arguments  the  sum,  difference,  and  product,  respec¬ 
tively,  of  their  first  two  arguments.  Mdiv  assigns  the  quotient  and  remainder,  respectively,  to  its 
third  and  fourth  arguments.  Sdiv  is  like  mdiv  except  that  the  divisor  is  an  ordinary  integer. 
Msgrt  produces  the  square  root  and  remainder  of  its  first  argument.  Rpow  calculates  a  raised  to 
the  power  b,  while  pow  calculates  this  reduced  modulo  m.  Min  and  meal  do  decimal  input  and 
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output. 

Use  the  -Imp  loader  option  to  obtain  access  to  these  functions.  -Imp. 
DIAGNOSTICS 


Illegal  operations  and  running  out  of  memory  produce  messages  and  core  images. 

FILES 

/usr/lib/libmp.a 


o 


Sun  Release  1.1 


Last  change:  15  March  1984 


7 


PL0T(3X) 


MISCELLANEOUS  FUNCTIONS 


PLOT(3X) 


NAME  ^ 

openpl,  eraae,  label,  line,  circle,  arc,  move,  cont,  point,  linemod,  space,  closepl  -  graphics  interface 

SYNOPSIS 

openplQ 

eraseO 

label(a) 
char  Bp} 

]!ne(xl,  yl,  xt,  y») 

elrcle(x,  y,  r) 

arc(x,  y,  xO,  yO,  xl,  yl) 

inove(Xf  y) 

coBi(}i,  y) 

polnt(x,-y) 

llncsQiMl(By 

eharsQr 

Bpaee(xO,  yOrXlr  yl) 
e!oBepI(]F 
DESORIPTTQN 

These  subroutmes  generate  graphic  output  in  a  relatively  device>ijulependent  manner.  See 

for  a  descriptiou  of  thei^  effect.  Openpf  must  be  us^  before  any  of  the  others  to  open  the  device 

for  writing.  Clottpl  flushes  the  output. 

String  arguments  to  Mel  and  linemod  are  nutt>terminated,  and  do  not  contam  newlines. 

Various  flavors  of  these  functions  exist  for  different  output  devices.  They  are  obtained  by  the  foL 
lowing  id(l)  options: 

— Iplot  device-independent  graphics  stream  on  standard  output  for  yioi(lG)  filters 

-1300  GSI 300  terminal 

-1300s  GSI  300S  terminal 

—1460  DASI  450  terminal 

-14014  Tektronix  4014  terminal 

plot(6),  plot(lG),  graph(lG) 

FILES 

/usr/lib/libplot.a 

/usr/lib/Iib300.a 

/usr/Ilb/Iib3008.a 

/U8r/iib/rib450.a 

/usr/lib/Ub4014.a 
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NAME 

tgetent,  tgetnum,  tgetflag,  tgetstr,  tgoto,  tputs  -  terminal  independent  operation  routines 

SYNOPSIS 

char  PC| 
char  *BCf 
char  *UPt 
■hort  ospaedi 

tgeteiit(bp,  name) 
char  *bp,  ’*name} 

tgetnum(id) 
char  ’"Idi 

tgetfi&g(Id) 
char  *ld| 

char  * 

tgetetr(ld»  area) 
char  *ld,  **areat 

char  * 

tgoto(cm,  deateoh  deatUne) 
char  *cmt 

tputa(epf  affcnt,  oute) 
register  char  *cpi 
Int  affcnti 
Int  (*oute)()} 

DESCRIPTION 

These  functions  extract  and  use  capabilities  from  the  terminal  capability  data  base  termcap{b). 
These  are  low  level  routines;  see  CMr*M(3X)  for  a  higher  level  package. 

Tgetent  extracts  the  entry  for  terminal  nome  into  the  buffer  at  bp.  Bp  should  be  a  character  buffer 
of  size  1024  and  must  be  retained  through  all  subsequent  calls  to  tgetnum,  tgetfiag,  and  Igetstr. 
Tgetent  returns  -I  if  it  cannot  open  the  termcap  file,  0  if  the  terminal  name  given  does  not  have 
an  entry,  and  1  if  all  goes  well.  It  will  look  in  the  environment  for  a  TERMCAP  variable.  If 
found,  and  the  value  does  not  begin  with  a  slash,  and  the  terminal  type  name  is  the  same  as  the 
environment  string  TERM,  the  TERMCAP  string  is  used  instead  of  reading  the  termcap  file.  If 
it  does  begin  with  a  slash,  the  string  is  used  as  a  path  name  rather  than  f  etcf  termcap.  This  can 
speed  up  entry  into  programs  that  call  tgetent,  as  well  as  to  help  debug  new  terminal  descriptions 
or  to  make  one  for  your  terminal  if  you  can’t  write  the  file  fetcj  termcap. 

Tgetnum  gets  the  numeric  value  of  capability  id,  returning  -1  if  is  not  given  for  the  terminal. 
Tgetfiag  returns  1  if  the  specified  capability  is  present  in  the  terminal’s  entry,  0  if  it  i»  not. 
Tgetttr  gets  the  string  value  of  capability  id,  placing  it  in  the  buffer  at  area,  advancing  the  area 
pointer.  It  decodes  the  abbreviations  for  this  field  deKribed  in  termcap{b),  except  for  cursor 
addressing  and  padding  information. 

Tgoto  returns  a  cursor  addressing  string  decoded  from  cm  to  go  to  column  deetcot  in  line  deetline. 
It  uses  the  external  variables  UP  (from  the  up  capability)  and  BC  (if  be  is  given  rather  than  be) 
if  necessary  to  avoid  placing  \n,  'D  or  in  the  returned  string.  (Programs  which  call  tgoto 
should  be  sure  to  turn  off  the  XTABS  bit(8),  since  tgoto  may  now  output  a  tab.  Note  that  pro¬ 
grams  using  termcap  should  in  general  turn  off  XTABS  anyway  since  some  terminals  use  control  1 
for  other  functions,  such  as  nondestructive  space.)  If  a  %  sequence  is  given  which  is  not  under¬ 
stood,  then  tgoto  returns  “OOPS”. 
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Tputf  decodes  the  leading  padding  information  of  the  string  ep;  affent  gives  the  number  of  lines 
affected  by  the  operation,  or  1  if  this  is  not  applicable,  oute  is  a  routine  which  is  called  with  each 
character  in  turn.  The  external  variable  o$petd  should  contain  the  encoded  output  speed  of  the 
terminal  as  described  in  Ui/{4).  The  external  variable  PC  should  contain  a  pad  character  to  be 
used  (from  the  pc  capability)  if  a  null  ('O)  is  inappropriate. 

FILES 

/usr/lib/libtermcap.a  -Itermcap  library 
/etc/termcap  data  base 

SEE  ALSO 

ex(l),  cuT8es(3X),  tty(4),  termcap(5) 


10 


Last  change:  9  February  1983 


Sun  Release  1.1 


INTRO(4) 


SPECIAL  FILES 


INTRO  (4) 


NAME 

intro  -  introduction  to  special  files  and  hardware  support 
DESCRIPTION 

This  section  describes  device  interfaces  to  the  operating  system  for  disks,  tapes,  serial  communicar 
tions,  high-speed  network  communications,  and  other  devices  such  as  mice,  frame  buffers  and  win- 
dow6» 

The  operating  system  can  be  built  with  or  without  many  of  the  devices  listed  here;  we  show  for 
most  devices  the  syntax  in  a  description  to  config(d)  to  cause  the  device  to  be  included  in  a  sys¬ 
tem.  For  mose  devices  we  also  give  a  DIAGNOSTICS  section  which  lists  the  error  messages 
which  the  device  may  produce  to  appear  on  the  system  console,  and  in  the  system  error  log  file 
/usr/ad  m/messages. 

Section  4  has  been  broken  up  according  to  machine  independent  device  interf2tces,  ^*4’'  entries, 
Sun  specific  devices  *‘4S**,  Vax  specific  devices  “4V”,  manual  pages  for  protocol  families  “4F”, 
and  manual  pages  for  protocols  and  raw  interfaces  “4P”. 

Most  devices  on  the  Sun  workstation  exist  on  the  Multibus,  whose  common  properties  are 
described  in  mi(4S). 

Devices  which  are  present  in  every  kernel  include  a  driver  for  the  paging  drum  rfrum(4),  drivers 
for  accessing  physical,  virtual  and  i/o  memory  mem(4S)  and  the  drivers  for  the  data  sink 
/dev/nuU,  nuI/(4). 

Communications  lines  are  most  often  used  with  the  terminal  driver  described  in  /^2f(4).  The  ter¬ 
minal  driver  runs  on  communications  lines  provided  either  by  a  communications  driver  such  as 
oc^(4S)  or  zs(4S)  or  on  a  more  virtual  terminal,  either  provided  by  the  Sun  console  monitor 
csns(4S)  or  a  true  pseudo-terminal  piy{i)  used  in  applications  such  as  windowing  or  remote  net¬ 
working. 

Magnetic  tapes  all  provide  the  interface  described  in  m^)o(4).  Tape  devices  for  the  Sun  include 
ar(4S)  and  ^m(4S). 

Disk  controllers  provide  standard  block  and  raw  interfaces,  as  well  as  a  set  of  ioctl’s  defined  in 
dh*o(4S)  supporting  disk  formatting  and  bad  block  handling.  Drivers  available  for  the  Sun 
include  2|/(4S)  and  ip(4S). 

The  operating  system  supports  one  or  more  protocol  familieo  supporting  local  network  communi¬ 
cations.  The  only  complete  protocol  family  in  this  version  of  the  system  is  the  Internet  protocol 
family  ine<(4F).  Each  protocol  family  provides  basic  services  to  each  protocol  implementation 
such  as  packet  fragmentation  and  reassembly,  routing,  addressing  and  basic  transport.  A  protocol 
family  is  normally  composed  of  a  number  of  protocols,  one  per  6ocket{2)  type.  It  is  not  required 
that  a  protocol  family  support  all  socket  types. 

The  primary  network  support  is  for  the  Internet  protocol  family  described  in  {ne^(4F).  Major  pro¬ 
tocols  in  this  family  include  the  Internet  Protocol  ip(4P)  describing  the  universal  datagram  for¬ 
mat,  the  stream  Transport  Control  Protocol  Icp(4P),  the  User  Datagram  Protocol  tidp(4P),  the 
Address  Resolution  Protocol  arp(4P),  and  the  Internet  Control  Message  Protocol  icmp(4P).  The 
primary  network  interface  is  for  the  10  Megabit  Ethernet  ec(4S);  a  software  loopback  interface 
Io(4)  also  exists.  General  properties  of  these  (and  all)  network  interfaces  are  described  in 

The  general  support  in  the  system  for  local  network  routing  is  described  in  rouKnp(4N);  these 
facilities  apply  to  all  protocol  families. 

Miscellaneous  devices  include  color  frame  buffers  c^(4S),  monochrome  frame  buffers  6u;^(4S),  the 
console  frame  buffer,  /&(4S),  the  console  mouse  mouse(4S)  and  the  window  devices  unn(4S). 
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NAME 

ar  -  Archive  1/4  inch  Streaming  Tape  Drive 
SYNOPSIS 

device  arO  at  mbO  ear  0x200  priority  3 
DESCRIPTION 

The  Archive  tape  controller  is  a  Sun  'QIC-II'  interface  to  aa  Archive  streaming  tape  drive.  It 
provides  a  standard  tape  interface  to  the  device,  see  m<>0(4),  with  some  deficiencies  listed  under 
BUGS  below. 

The  maximum  blocksiae  for  the  raw  device  is  limited  onljr  by  available  memory. 

FILES 

/dev/rarO 

/dev/nrarO  non-rewinding 

SEE  ALSa 

mtio(4),  tm(4S) 

Archive  Intelligent  Tape  Drive  Theory  of  Operation,  Archive  Corporation  (Sun  8000-105&-01) 
Archive  Product  Manual  (Sidewinder  1/4”  Streaming  Cartridge  Tape  Drive)  (Sun  800-062S-01) 

Sun  1/4”  Tape  Interface  -  User  Manual  (Sun- 800-0415-01) 

DIAGNOSTICS 

ar%dr  would  not  Intttallse. 

ar%dt  alresMly  open.  The  tape  can  be  open  by  onl^  one  process  at  a  time. 

ar%dt  no  such  chrlve. 

aE%di  no  cartridge  In  drive. 

ar%dt  cartridge  Is  write  protected. 

art  Interrupt  from  utritlaUsed  controller  %x. 

ar%dt  many  retries^  consider  retiring  this  tape. 

ar%dt  %h  error  at  block  #  %d  punted. 

ar%dt  %b  error  at  block  #  %d. 

art  giving  up  on  Rdy,  try  again. 

BUGS 

The  tape  cannot  reverse  direction  so  BSF,  BSR  and  FSR  are  not  available. 

The  system  will  hang  if  the  tape  is  removed  while  running. 

When  using  the  raw  device,  the  number  of  bytes  in  any  given  transfer  must  be  a  multiple  of  512 
bytes..  If  it  is  not,  the  device  driver  returns  an  ttitx. 
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NAME 

arp  -  Address  Resolution  Protocol 

SYNOPSIS 

pseudo-device  ether 

DESCRIPTION 

ARP  is  a  protocol  used  to  dynamically  map  between  DARPA  Internet  and  lOMb/s  Ethernet 
addresses.  It  is  used  by  all  the  lOMb/s  Ethernet  interface  drivers. 

ARP  caches  Internet-Ethernet  address  mappings.  When  an  interface  requests  a  mapping  for  an 
address  not  in  the  cache,  ARP  queues  the  message  which  requires  the  mapping  and  broadcasts  a 
message  on  the  associated  network  requesting  the  address  mapping.  If  a  response  is  provided,  the 
new  mapping  is  cached  and  any  pending  messages  are  transmitted.  ARP  will  queue  at  most  one 
packet  while  waiting  for  a  mapping  request  to  be  responded  to;  only  the  most  recently  “transmit¬ 
ted”  packet  is  kept. 

To  enable  communications  with  systems  which  do  not  use  ARP,  ioctls  are  provided  to  enter  and 
delete  entries  in  the  Intemet-to-Ethemet  tables.  Usage: 

#lnelud«  <sya/loetl.h> 

#tnelude  <syB/aocketJi> 

#lnclude  <net/if.h> 

■truet  arpreq  arpreq; 


loetI(a»  SIOCSARPy  (caddrjt)ftarpreq)f 
loetl(s,  SIOCGARP,  (eaddr_t)&arpre^{ 
loctl(B,  SIOCDARPf  (caddr_t)ikar pr«q); 

Each  ioctl  takes  the  same  structure  as  an  argument.  SIOCSARP  sets  an  ARP  entry,  SIOCGARP 
gets  an  ARP  entry,  and  SIOCDARP  deletes  an  ARP  entry.  These  ioctls  may  be  applied  to  any 
socket  descriptor  s,  but  only  by  the  super-user.  The  urpre;  structure  contains: 


/• 

•  ARP  ioctl  request. 

V 


struct  arpreq  { 

struct  sockaddr  arp_pa; 
struct  sockaddr  arp_ha; 
int  arp_flags; 


}; 

/*  aiP-flaSs  field  values  •/ 


#define  ATF_COM 
#deflneATF_PERM  4 
#defineATFJ»UBL  8 


/*  protocol  address  •/ 
/*  hardware  address  */ 
/*  flags  */ 


2  /•  completed  entry  (arp_ha  valid) 

/*  permanent  entry  •/ 

/*  publish  (respond  for  other  host)  */ 


*/ 


The  address  family  for  the  arp^>a  sockaddr  must  be  AFJNET;  for  the  arpjia  sockaddr  it  must 
be  AF_UNSPEC.  The  only  flag  bits  which  may  be  written  are  ATF_PERM  and  ATF_PUBL. 
ATF^ERM  causes  the  entry  to  be  permanent  if  the  ioctl  call  succeeds.  The  peculiar  nature  of 
the  ARP  tables  may  cause  the  ioctl  to  fail  if  more  than  4  (permanent)  Internet  host  addresses 
hash  to  the  same  slot.  ATF^PUBL  specifies  that  the  ARP  code  should  respond  to  ARP  requests 
for  the  indicated  host  coming  from  other  machines.  This  allows  a  Sun  to  act  as  an  ’’ARP  server"’ 
which  may  be  useful  in  convincing  an  ARP-only  machine  to  talk  to  a  non-ARP  machine. 


ARP  watches  passively  for  hosts  impersonating  the  local  host  (i.e.  a  host  which  responds  to  an 
ARP  mapping  request  for  the  local  host’s  address). 


DIAGNOSTICS 

duplicate  IP  address!!  sent  f^om  ethernet  address:  %xi%xi%xi%xi%xx%x,  ARP  has 
discovered  another  host  on  the  local  network  which  responds  to  mapping  requests  for  its  own 


Sun  Release  1.1 


Last  change:  11  January  1984 


3 


ARP(4P) 


SPECIAL  FILES 


ARP(4P) 


lotemet  address. 

SEE  ALSO 

ec(4S),  ie(4S),  inet(4F),  arp(8C),  ifcoiifig(8C) 

An  Ethernet  Address  Resolution  Protocol  RFC826,  Dave  Plummer,  MIT  (Sun  800-105^1) 

BUGS 

ARP  packets  on  the  Ethernet  use  only  42  bytes  of  data,  however,  the  smallest  legal  Ethernet 
packet  is  60  bytes  (not  including  CRC).  Some  systems  may  not  enforce  the  minimum  packet  size, 
others  will. 
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BK(4) 


SPECIAL  FILES 


BK(4) 


NAME 

bk  -  line  discipline  for  tnachine*inachine  communication 

SYNOPSIS 

pseudo-device  bk 

DESCEIPTION 

This  line  discipline  provides  a  replacement  for  the  tty  driver  tty(4)  when  high  speed  output  to  and 
especially  input  from  another  machine  is  to  be  transmitted  over  an  asynchronous  communications 
line.  The  discipline  was  designed  for  use  by  a  (now  obsolete)  store-and-forward  local  network  run¬ 
ning  over  serial  lines.  It  may  be  suitable  for  uploading  of  data  from  microprocessors  into  the  sys¬ 
tem.  If  you  are  going  to  send  data  over  asynchronous  communications  lines  at  high  speed  into 
the  system,  you  must  use  this  discipline,  as  the  system  otherwise  may  detect  high  input  data  rates 
on  terminal  lines  and  disable  the  lines;  in  any  case  the  processing  of  such  data  when  normal  ter¬ 
minal  mechanisms  are  involved  saturates  the  system. 

The  line  discipline  is  enabled  by  a  sequence: 

^Include  <sgtty.h> 

int  IdlBC  s  NETLDISC,  Aides} ... 

ioetI(Aldes,  TIOCSETD,  &ldlse)} 

A  typical  application  program  then  reads  a  sequence  of  lines  from  the  terminal  port,  checking 
header  and  sequencing  information  on  each  line  and  acknowledging  receipt  of  each  line  to  the 
sender,  who  then  transmits  another  line  of  data.  Typically  several  hundred  bytes  of  data  and  a 
smaller  amount  of  control  information  will  be  received  on  each  handshake. 

The  old  standard  teletype  discipline  can  be  restored  by  doing: 

Idlse  ss  OTTYDISC} 
loetl(Aldes,  TIOCSETD,  &Id!se)} 

While  in  networked  mode,  normal  teletype  output  functions  take  place.  Thus,  if  an  8  bit  output 
data  path  is  desired,  it  is  necessary  to  prepare  the  output  line  by  putting  it  into  RAW  mode  using 
ioetl(2).  This  must  be  done  before  changing  the  discipline  with  TIOCSETD,  as  most  ioctl[2) 
calls  are  disabled  while  in  network  line-discipline  mode. 

When  in  network  mode,  input  processing  is  very  limited  to  reduce  overhead.  Currently  the  input 
path  is  only  7  bits  wide,  with  newline  the  only  character  terminating  an  input  record.  Each  input 
record  must  be  read  and  acknowledged  before  the  next  input  is  read  as  the  system  refuses  to 
accept  any  new  data  when  there  is  a  record  in  the  buffer.  The  buffer  is  limited  in  length,  but  the 
system  guarantees  to  always  be  willing  to  accept  input  resulting  in  512  data  characters  and  then 
the  terminating  newline. 

User  level  programs  should  provide  sequencing  and  checksums  on  the  information  to  guarantee 
accurate  data  transfer. 

SEE  ALSO 

tty(4) 

DIAGNOSTICS 

None. 
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BW0NE(4S) 


SPECIAL  FILES 


BWONE(4S) 


NAME 

bwone  -  Sun  one  black  and  white  frame  buffer 
SYNOPSIS 

device  bwoneO  at  mbO  car  OxcOOOO  priority  3 

DESCRIPTION 

The  bwone  interf2fcce  provides  access  to  Sun^l  black-^and-white  graphics  controller  boards.  It  sup¬ 
ports  the  FBIOGTYPE  ioctl  which  a  program  can  use  to  inquire  as  to  the  characteristics  of  the 
display  device;  see  fb%o{4S) 

It  supports  the  FBIOGPDCRECT  ioctl  which  allows  SunWindows  to  be  run  on  it;  see  /Jic(4S) 

Reading  or  writing  to  the  frame  buffer  is  not  allowed  -  you  must  use  the  mmap(2)  system  call  to 
map  the  board  into  your  address  space. 

FILES 

/dev/bwo]ie|0*0^ 

SEE  ALSO 

mmap(2)»  Ib(4S),  fbio(4S) 

Sun  1024  Video  Board  -  User  Manual  (Sun  800-0420) 

DIAGNOSTICS 

None. 

BUGS 

Use  of  verticaUretrace  interrupts  is  not  supported. 


o 
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BWTWO(4S) 


SPECIAL  FILES 


BWTW0(4S) 


NAME 

bwtwo  -  Sun  two  black  and  white  frame  buffer 
SYNOPSIS 

device  bwtwoO  at  mbO  car  0x700000  priority  3 
DESCRIPTION 

The  bwtwo  interface  provides  access  to  Sun-2  Monochrome  Video  Controller  boards.  It  supports 
the  FBIOGTYPE  ioctl  which  a  program  can  use  to  inquire  as  to  the  characteristics  of  the  display 
device;  see /(io(4S) 

It  supports  the  FBIOGPKRECT  ioctl  which  allows  SunWindows  to  be  run  on  it;  see  /6ia(4S) 

Reading  or  writing  to  the  frame  buffer  is  not  allowed  -  you  must  use  the  mmap(2)  system  call  to 
map  the  board  into  your  address  space. 

FILES 

/dev/bwtwo[0-9] 

SEE  ALSO 

mmap(2),  fb(4S),  fbio(4S) 

DIAGNOSTICS 

None. 

BUGS 

Use  of  vertical-retrace  interrupts  is  not  supported. 


Q 
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CGONE(4S) 


SPECIAL  FILES 


CGONE(4S) 


NAME 

cgone  -  Sun-l  color  graphics  interface 
SYNOPSIS 

device  cgoneO  at  mbO  ear  OxeSOOO  priority  8 

DESCRIPTION 

The  egone  interface  provides  access  to  the  Sun-l  color  graphics  controller  board,  which  is  nor¬ 
mally  supplied  with  a  13”  or  10”  RS170  color  monitor.  It  provides  the  standard  frame  buffer 
interface  as  defined  in  /(to(4S). 

It  supports  the  FBIOGPDCRECT  ioctl  which  allows  SunWindows  to  be  run  on  it;  see  /iio(4S) 

The  hardware  consumes  16  kilobytes  of  Multibus  memory  space.  The  board  starts  at  standard 
addresses  QxESOOO  or  OxECOOO.  The  board  must  be  configur^  for  interrupt  level  3. 

FILES 

/dev/cg<«e(l-^ 

SEE  ALSO 

mmap(2},-fbio(4S) 

Sun  CMor  Video  Board  User's  Manual  (Suff  8000-0308,  Rev  B) 

Barco  GD33  Color  Display  120V AC  Operation  Ins^ctiona  (13”)  (Sun  800-1002^1) 

Barco  Color  Display  CX)  252  120/220VAC  Operation  Guide  (10”)  (Sun  800-1003-01) 

DIAGNOSTICS 

None.- 

BUGS 

Use  of  color  board  vertical-ietrace  interrupts,  is  not  supported. 
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C0NS(4S) 


SPECIAL  FILES 


C0NS(4S) 


NAME 

cons  -  driver  for  Sun  console 
SYNOPSIS 

None;  included  in  standard  system. 

DESCRIPTION 

Cone  is  an  indirect  driver  for  the  Sun  workstation  console,  which  implements  a  standard  UNIX 
terminal.  Cone  is  implemented  by  calling  the  PROM  resident  monitor  to  perform  I/O  to  and 
from  the  current  system  console,  which  is  either  a  Sun  frame  buffer  or  an  RS232  port. 

When  the  Sun  window  system  «;m(4S)  is  active,  console  input  is  directed  through  the  window  sys¬ 
tem  rather  than  being  read  from  /dev/console. 

An  ioctl  TIOCCONS  may  be  applied  to  serial  devices  other  than  the  console  to  cause  output 
which  would  normally  appear  on  the  console  to  instead  be  routed  to  the  other  devices.  This  is 
used  by  the  window  system  which  does  a  TIOCCONS  on  a  pseudo- terminal  to  cause  console  out¬ 
put  to  be  routed  there  rather  than  to  the  screen  through  the  PROM  monitor,  since  routing  output 
through  the  PROM  destroys  the  integrity  of  the  screen. 

FILES 

/dev /console 

/dev/ttya  alternate  console  (serial  port) 

SEE  ALSO 

oct(4S),  tty(4),  Z8(4S) 

BUGS 

TIOCCONS  should  be  restricted  to  the  owner  of  /dev/console. 

o 


o 
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DKI0(4S) 


SPECIAL  FILES 


DKI0(4S) 


NAME 

dkio  -  generic  disk  control  operations 
DESCRIPTION 

AM  Sun  disk  drivers  support  a  set  of  ioctPs  for  disk  formattting  and  labelling  operations.  Basic  to 
these  ioctl's  are  the  definitions  in  <sun/dkio.h>: 

/* 

*  Structures  and  definitions  for  disk  io  control  commands 

•/ 


f*  Disk  identification  */ 
struct  dkjnfo  { 


iat 

dkijctlr; 

/♦  controller  address  */ 

short 

dkLttnit; 

/*  unit  (slave)  address  */ 

short 

dkijctype; 

/*  controller  type  */ 

short 

dkLflngs; 

/*  flags  */ 

/I 

/*  controller  t3rpe8  */ 

#defineDKC_UNKNOWN  0 

#defineDKC_SMD2180  I 

#defineDKCJCY440  4 

#defineDKC_pSD5215  5 

#defineDKCJCY450  6 

#defineDKC_SCSI  7 


/*  flags  */ 

#defineDKLBADl44  01 
#dcflne  DKLMAPTRK  02 
#deflneDKI_FMTTRK  04 
#deflneDKI_FMTVOL  0x08 


/*  use  DEC  std  144  bad  sector  fwding  */ 
/*  controller  does  track  mapping  */ 

/*  formats  only  full  track  at  a  time  */ 

/*  formats  only  full  volume  at  a  time  *j 


I*  Definition  of  a  disk’s 
struct  dk_geom  { 

unsigned  short 
unsigned  short 
unsigned  short 
unsigned  short 
unsigned  short 
unsigned  short 
unsigned  shorf 
unsigned  short 
unsigned  short 
unsigned  short 

}; 


geometry  */ 

dkg_ncyl; 

dkg_acyl; 

dkg_bcyl; 

dkgjibead; 

dkgjbhead; 

dkg_n8ect; 

dkgjntrlv; 

dkg_gapl; 

dkg_gap2; 

dkgjextrajlOj; 


/*  Disk  format  request  */ 
struct  dk_fmt  { 

daddr_t  dkf_blkno; 
daddr_t  dkf_nblk; 
ujchar  dkf_fill; 

}; 


/*  Disk  re-map  request  */ 


j*  ^  of  data  cylinders  •/ 

/•  #  of  alternate  cylinders  */ 

/*  cyl  offset  (for  fixed  head  area)  */ 
/*  #  of  heads  */ 

/*  head  offset  (for  Larks,  etc.)  */ 

/♦  #  of  sectors  per  track  */ 

/•  interleave  factor  */ 

/*  gaq>  1  size  •/ 

/•  gsq>  2  size  •/ 

/*  for  compatible  expansion  */ 


/*  starting  block  */ 
/•  #  of  blocks  */ 

/*  fill  data  */ 


10 


Last  change:  20  March  1084 


Sun  Release  1.1 


DKI0(4S) 


SPECIAL  FILES 


DKIO{4S) 


/*  from  block  */ 
/*  to  block  */ 

/*  #  blocks  V 
/*  fill  data  */ 


f*  disk  io  control  commands  */ 

#deflneDKIOCHDR  JO(d,  1)  /*  next  I/O  will  read/write  header  */ 

#define  DKIOCGGEOM  _IOR(d,  2,  struct  dk_seom)  /*  Get  geometry  */ 

#deflne  DKIOCSGEOM  JOW(d,  3,  struct  dk_geom)  /*  Set  geometry  ♦/ 

#defincDKIOCGPART  _IOR(d,  4,  struct  dk_map)  /*  Get  partition  info  */ 

#defineDKIOCSPART  JOW(d,  5,  struct  dk_map)  /*  Set  partition  info  */ 

#defineDKIOCFMT  JOW(d,  6,  struct  dk_fmt)  /*  Format  •/ 

#defineDKIOCMAP  _IOW(d,  7,  struct  dk_mapr)  /*  Map  */ 

#defineDKIOCINFO  JOR(d,  8,  struct  dkjnfo)  /•  Get  info  */ 

The  DKIOCGINFO  iocti  returns  a  dkjnfo  structure  which  tells  the  kind  of  the  controller  and 
attributes  about  how  bad-block  processing  is  done  on  the  controller.  Bad  sectors  can  then  be  pro¬ 
cessed  using  either  the  DKIOCMAP  request,  which  causes  a  sector  to  be  re-mapped  on  the  disk, 
or  the  DKIOCFMT  request  which  causes  a  sector  to  be  re-formatted.  To  read  or  write  the  header 
on  a  disk  sector  the  DKIOCHDR  iocti  can  be  used,  it  causes  the  next  read  or  write  request  to  also 
read  or  write  the  (drive-type-specific)  header  data. 

The  DKIOCGPART  and  DKIOCSPART  get  and  set  the  controller’s  current  notion  of  the  parti¬ 
tion  table  for  the  disk  (without  changing  the  partition  table  on  the  disk  itself),  while  the 
DKIOCGGEOM  and  DKIOCSGEOM  ioctl’s  do  similar  things  for  the  per-drive  geometry  informa¬ 
tion.  These  can  be  used  to  format  a  drive,  where  the  label  does  not  exist  before  the  drive  is  for¬ 
matted. 

SEE  ALSO 

ip(4S),  xy(4S) 

BUGS 

The  DKIOCMAP  and  DKIOCFMT  request  are  incompletely  implemented. 


struct  dk^mapr  { 

daddr.t  dkm_fblk ; 
daddr_t  dkm_tblk; 
daddr_t  dkm.nblk; 
u  char  dkm  fill; 

>; 
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DBUM(4) 


SPECIAL  FILES 


DRUM(4) 


NAME 

drum  -  paging  device 


SYNOPSIS 

None;  included  with  standard  system. 

DESCRIPTION 

This  file  refers  to  the  paging  device  in  use  by  the  system.  This  may  actual^  be  a  subdevice  of 
one  of  the  disk  drivers,  but  in  a  system  with  paging  interleaved  across  multiple  disk  drives  it  pro¬ 
vides  an  indirect  driver  for  the  multiple  drives. 

FILES 

/dev /drum 

BUGS 

Reads  from  the  drum  are  not  allowed  across  the  Interleaving  boundaries.  Since  these  only  occur 
every  .SMbyCes  or  so,  and  since  the  system  never  allocates  blocks  across  the  boundary,  this  is  usu¬ 
ally  not  a  problem. 
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SPECIAL  FILES 


EC(4S) 


NAME 

ec  -  3Gom  10  Mb/s  Ethernet  interface 
SYNOPSIS 

device  ecO  at  mbO  csr  OxeOOOO  priority  3 
DESCRIPTION 

The  ec  interface  provides  access  to  a  10  Mb/s  Ethernet  network  through  a  3COM  controller.  For 
a  general  description  of  network  interfaces  see  ry(4N). 

The  hardware  consumes  8  kilobytes  of  Multibus  memory  space.  This  memory  is  used  for  internal 
buffering  by  the  board.  The  board  starts  at  standard  addresses  OxEOOOO  or  OxE2000.  The  board 
must  be  configured  for  interrupt  level  3. 

The  interface  software  implements  an  exponential  backoff  algorithm  when  notified  of  a  collision 
on  the  cable. 

The  interface  handles  the  Internet  protocol  family,  with  the  interface  address  maintained  in  Inter* 
net  format.  The  Address  Resolution  Protocol  arp(4P)  is  used  to  map  32-bit  Internet  addresses 
used  in  inel(4P)  to  the  48*bit  addresses  used  on  the  Ethernet. 

DIAGNOSTICS 

BC%dt  Ethernet  Jammed.  After  10  failed  transmissions  and  backoffs  using  the  exponential 
backoff  algorithm,  the  packet  was  dropped. 

ee%di  can^t  handle  mf%d.  The  interface  was  handed  a  message  with  addresses  formatted  in  an 
unsuitable  address  family;  the  packet  was  dropped. 

SEE  ALSO 

arp(4N),  if(4N),  inet(4F) 

3COM  3C400  Multibus  Ethernet  Controller  Reference  Manual  (Sun  800-0398) 

BUGS 

The  interface  hardware  is  not  capable  of  talking  to  itself,  making  diagnosis  more  difficult. 
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EN(4S) 


SPECIAL  FILES 


EN(4S) 


NAME 

en  -  Sun  3  Mb/s  experimental  Ethernet  interface 
SYNOPSIS 

device  enO  at  mbO  csr  0x100  priority  3 
DESCRIPTION 

The  en  interface  provides  access  to  a  3  Mb/s  Ethernet  network*  The  host’s  address  is  discovered 
at  boot  time  by  probing  the  Ethernet  address  register.  For  a  general  description  of  network  inter¬ 
faces,  sec  if{4N). 

The  board  consumes  256  bytes  of  Multibus  I/O  space  starting  at  standard  address  Ox  100. 

The  interface  handles  both  Internet  and  PUP  protocol  families,  with  the  interface  address  main¬ 
tained  in  Internet  format.  PUP  addresses  are  converted  to  Internet  addresses  by  subsituting  PUP 
network  and  host  values  for  Internet  network  and  imp  values,  and  setting  the  Internet  host 
number  to  zero. 

DIAGNOSTICS 

6ii%d}  output  error.  The  hardware  indicated  an  error  on  the  previous  transmission. 

en%d:  send  error.  After  16  retransmissions  the  packet  was  dropped. 

en%di  Input  error.  The  hardware  indicated  an  error  in  reading  a  packet  off  the  cable. 

en%d}  can’t  handle  af%d«  The  interface  was  handed  a  message  with  addresses  formatted  in 
an  unsuitable  address  fami^;  the  packet  was  dropped. 

SEE  ALSO 

if  (4N),  inet(4F) 

Sun  3Mbit  Ethernet  Board,  User’s  Manual  (Sun  800-0392) 

BUGS 

This  hardware  and  driver  are  not  supported. 
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FB(4S) 


SPECIAL  FILES 


FB(4S) 


o 

NAME 

fb  -  driver  for  Sun  console  frame  buffer 
SYNOPSIS 

None;  included  in  standard  system. 

DESCRIPTION 

The  fb  driver  provides  indirect  access  to  a  Sun  graphics  controller  board.  It  is  an  indirect  driver 
for  the  Sun  workstation  console’s  frame  buffer.  At  boot  time,  the  workstation’s  frame  buffer  dev¬ 
ice  is  determined  from  information  from  the  Monitor  Proms  and  set  to  be  the  one  that  fb  will 
indirect  to.  The  device  driver  for  the  console’s  frame  buffer  must  be  configured  into  the  kernel  so 
that  this  indirect  driver  can  access  it. 

The  idea  behind  this  driver  is  that  user  programs  can  open  a  known  device,  query  its  characteris¬ 
tics  and  access  it  in  a  device  dependent  way,  depending  on  the  type.  Fb  redirects  open[2), 
cto9e{2),  ioeU(2),  and  mm«p(2)  calls  to  the  real  frame  buffer.  All  of  the  Sun  frame  buffers  support 
the  same  general  interface;  see  /(to(4S) 

FILES 

/dev/fb 

CtPIT  AT  CtO 

fbio(4S),  bwone(4S),  bwtwo(4S) 
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NAME 

fbio  -  general  properties  of  frame  buffers 


DESCRIPTION 

All  of  the  Sun  frame  buffers  support  the  same  general  interface.  Each  responds  to  a  PBIOGTYPE 
ioeU{2)  which  returns  information  in  a  structure  defined  in  <BUtt/fbio.b>: 


struct  fbtype  { 

int  fb.^pe; 

int  fBJheight; 

int  fb.width; 

int  tb^deptb; 

int  fb.emsae; 

int  fb^size; 

h 

#define  FBTYPEJSUNIBW 
#define  FBTYPEJSONIGOLOR 
#define  FBTYPE^SCNfiBW 


/*  as  defined  below  */ 

/•  in  pbcels 
f*  in  pixels  •/ 

/•  bits  per  pixel  */ 

/•  size  of  color  map  (entries)  */ 
/*  total  size  in  bytes  */ 


0 

1 

2 


Each  device  has  a^FBTYPE  which  is  used  by  higber^level  software  to  determine  bow  to  perform 
raster-op  and  other  functions.  Each  device  is  used  by  opening  it,  doing  a  FBIOGTYPE  ioetl  to 
see  which  frame  buffer  type  is  present,  and  thereby  selecting  the  appropriate  device  management 
routines. 

Full  fledged  frame  buffers,  i.e.,  those  that  expect  to  run  SunWindows,  implement  an  FBIOGPDC- 
RECT  ioeil{2),  which  returns  a  pixrect.  This  call  is  made  only  from  inside  the  kernel.  The 
returned  pixrect  is  used  by  wio(4S)  for  cursor  tracking  and  colormap  loz^Iing. 

SEE  ALSO 

mmap(2),  fb(4S),  bwone(4S),  bwtwo(4S),  cgone(4S)[,  win(4S) 
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NAME 

icmp  -  Internet  Control  Message  Protocol 
SYNOPSIS 

None;  included  automatically  with  me^(4P). 

DESCRIPTION 

The  Internet  Control  Message  Protocol  ICMP  is  used  by  gateways  and  destination  hosts  which 
process  datagrams  to  communicate  errors  in  datagram  processing  to  source  hosts.  (The  datagram 
level  of  Internet  is  discussed  in  ip(4P).)  ICMP  uses  the  basic  support  of  IP  as  if  it  were  a  higher 
level  protocol,  however  ICMP  is  actually  an  integral  part  of  IP. 

ICMP  messages  are  sent  in  several  situations:  for  example  when  a  datagram,  cannot  reach  its  des¬ 
tination,  when  the  gateway  does  not  have  the  buffering  capacity  to  forward  a  datagram,  and  when 
the  gateway  can  direct  the  host  to  send  traffic  on  a  shorter  route* 

The  Internet  protocol  is  not  designed  to  be  absolutely  reliable.  The  purpose  of  these  control  mes¬ 
sages  is  to  provide  feedback  about  problems  in  the  communication  environment,  not  to  make  IP 
reliable.  There  are  still  no  guarantees  that  a  datagram  will  be  delivered  or  a  control  message  will 
be  returned.  Some  datagrams  may  still  be  undelivered  without  any  report  of  their  loss.  The 
higher  level  protocols  which  use  IP  must  implement  their  own  reliability  procedures  if  reliable 
communication  is  required. 

The  ICMP  messages  typically  report  errors  in  the  processing  of  datagrams.  To  avoid  the  infinite 
regress  of  messages  about  messages  etc.,  no  ICMP  messages  are  sent  about  ICMP  messages.  Also 
ICMP  messages  are  only  sent  about  errors  in  handling  fragment  0  of  fragmented  datagrams. 

There  are  il  types  of  ICMP  packets  which  can  be  received  by  the  system.  They  are  defined  in 
this  excerpt  from  <netinet/ipjcmp.h>,  which  also  defines  the  values  of  some  additional  codes 
further  specifying  the  cause  of  certain  errors. 

/* 

*  Definition  of  type  and  code  field  values 

V 

#deaneICMP_ECHOREPLY  0 

#deflneICMP_UNREACH  3 

#dcfliie  ICMP_UNREACH_NET 

#deflne  ICMP.UNREACHJHOST 

#deflne  ICMPJJNREACHJPROTOCOL 

#deflB«  ICMP_UNREACH_PORT 

#define  ICMP^UNREACH.NEEDFRAG 

#deflne  ICMP_UNREACH_SRCFAIL 

#deflneICMP_SOURCEQUENCH  4 

#deflneICMP_PEDIRECT  6 

#deflne  ICMP_REDIRECT_NET  0 

#deflne  ICMPJIEDIRECTJHOST  1 

#deflne  ICMPJREDIRECT_TOSNET  2 

#define  ICMPJREDIRECT_TOSHOST  3 

#defiBeICMP_ECHO  8 

#defiBeICMP_TIMXCEED  11 

#deflne  ICMP_TIMXCEED_INTRANS  0 

#defiBe  ICMP_TIMXCEED_REASS  1 

#defiBe  ICMP_PARAMPROB  12 

#dcaBeICMP_TSTAMP  13 

#deaB«ICMP_TSTAMPREPLY  14 

#deaneICMP_IREQ  15 

#dcaae  ICMP_IREQREPLY  16 


/*  echo  reply  */ 

j*  dest  unreachable,  codes:  */ 

0  f*  bad  net  */ 

1  /*  bad  host  */ 

2  /*  bad  protocol  */ 

3  /*  bad  port  */ 

4  /*  IP _PF  caused  drop  */ 

6  /*  sre  route  failed  */ 

/*  packet  lost,  slow  down  */ 

/*  shorter  route,  codes:  */ 
f*  for  network  */ 

/*  for  host  */ 

/*  for  tos  and  net  */ 

/*  for  tos  and  host  */ 
f*  echo  service  */ 

/*  time  exceeded,  code:  */ 

j*  ttl==0  in  transit  */ 
/*  ttl==0  in  reass  */ 

/*  ip  header  bad  */ 

/*  timestamp  request  */ 

/*  timestamp  reply  */ 

/*  information  request  */ 
f*  information  reply  */ 
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Arriving  ECHO  and  TSTAMP  packets  cause  the  system  to  generate  ECHOREPLY  and 
TSTAMPREPLY  packets,  IREQ  packets  are  not  yet  processed  by  the  system,  and  are  discarded, 
UNREACH,  SOURCEQUENCH,  TIMXCEED  and  PARAMPROB  packets  are  processed  inter¬ 
nally  by  the  protocols  implemented  in  the  system,  or  reflected  to  the  user  if  a  raw  socket  is  being 
used;  see  ip(4P).  REDIRECT,  ECHOREPLY,  TSTAMPREPLY  and  IREQREPLY  are  also 
reflected  to  users  of  raw  sockets.  In  addition,  REDIRECT  messages  cause  the  kernel  routing 
tables  to  be  updated;  see  rnnltnp(4N), 

SEE  ALSO 

inet(4F),  ip(4P) 

Internet  Control  Message  Protocol,  RFC792,  J,  Pcstel,  USC-ISI  (Sun  800-1064-01) 

BUGS 

IREQ  messages  are  not  processed  properly:  the  address  fields  are  not  set. 

Messages  which  are  source  routed  are  not  sent  back  using  inverted  source  routes,  but  rather  go 
back  through  the  normal  routing  mechanisms. 
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NAME 

if  -  general  properties  of  network  interfaces 
DESCRIPTION 

Each  network  interface  in  a  system  corresponds  to  a  path  through  which  messages  may  be  sent 
and  received.  A  network  interface  usually  has  a  hardware  device  associated  with  it,  though  cer¬ 
tain  interfaces  such  as  the  loopback  interface,  /o(4),  do  not. 

At  boot  time  each  interface  which  has  underlying  hardware  support  makes  itself  known  to  the 
system  during  the  autoconflguration  process.  Once  the  interface  has  acquired  its  address  it  is 
expected  to  install  a  routing  table  entry  so  that  messages  may  be  routed  through  it.  Most  inter¬ 
faces  require  some  part  of  their  address  specified  with  an  SIOCSIFADDR  ioctl  before  they  will 
allow  traffic  to  flow  through  them.  On  interfaces  where  the  network-link  layer  address  mapping  is 
static,  only  the  network  number  is  taken  from  the  ioctl;  the  remainder  is  found  in  a  hardware 
specific  manner.  On  interfaces  which  provide  dynamic  network-link  layer  address  mapping  facili¬ 
ties  (e.g.  lOMb/s  Ethernets  using  (irp(4P),),  the  entire  address  specified  in  the  ioctl  is  used. 

The  following  ioctl  calls  may  be  used  to  manipulate  network  interfaces.  Unless  specified  other¬ 
wise,  the  request  takes  an  ifreq  structure  as  its  parameter.  This  structure  has  the  form 

struct  ifreq  { 

char  ifr_name(16j;  name  of  interface  (e.g.  ^ccO”)  */ 

union  { 

struct  sockaddr  ifru^addr; 
struct  sockaddr  ifru^dstaddr; 
short  ifru^flags; 

}  ifrjfru; 

#define  ifr.addr  ifr Jfru.ifru^addr  /*  address  */ 

#define  ifrjdstaddr  ifrjfru.ifrujdstaddr  /*  other  end  of  p-to-p  link  ’•'/ 

#deflne  ifrjSags  ifrjfru.ifru^flags  flags  */ 

}; 

SIOCSIFADDR 

Set  interface  address.  Following  the  address  assignment,  the  “initialization”  routine  for 
the  interface  is  called. 

SIOCGIFADDR 

Get  interface  address. 

SIOCSIFDSTADDR 

Set  point  to  point  address  for  interface. 

SIOCGIFDSTADDR 

Get  point  to  point  address  for  interface. 

SIOCSIFFLAGS 

Set  interface  flags  field.  If  the  interface  is  marked  down,  any  processes  currently  routing 
packets  through  the  interface  are  notified. 

SIOCGIFFLAGS 

Get  interface  flags. 

SIOCGIFCONF 

Get  interface  configuration  list.  Th»  request  takes  an  ifeonf  structure  (see  below)  as  a 
value-result  parameter.  The  ife_len  field  should  be  initially  set  to  the  size  of  the  bufler 
pointed  to  by  ifc_buf.  On  return  it  will  contain  the  length,  in  bytes,  of  the  configuration 
list. 

/* 

*  Structure  used  in  SIOCGIFCONF  request. 

*  Used  to  retrieve  interface  configuration 
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*  for  machine  (useful  for  programs  which 

*  must  know  all  networks  accessible), 

V 

struct  ifconf  { 

int  ifcjen;  /*  size  of  associated  buffer  */ 

union  { 

caddr^t  ifcu^buf; 
struct  ifreq  *ifcu_req; 

)  ifcjfcu; 

#define  ifc_buf  ifc_ifcu.ifcu_buf  /•  buffer  address  */ 

#deflne  ifc_req  ifcJfcu.ifcu_Teq  /*  array  of  structures  returned  */ 

}: 

SEE  ALSO 

arp(4P),  ec(4S),  en(4S),  Io(4) 
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NAME 

inet  -  Internet  protocol  family 

SYNOPSIS 

options  INBT 
pwudo*devie«  Inet 

DESCRIPTION 

The  Internet  protocol  family  is  a  collection  of  protocols  layered  atop  the  Internet  Protocol  (IP) 
transport  layer,  and  utilizing  the  Internet  address  format.  The  Internet  family  provides  protocol 
support  for  the  SOCK_STREAM,  SOCK_DGRAM,  and  SOCK_RAW  socket  types;  the 
SOCK_RAW  interface  provides  access  to  the  IP  protocol. 

ADDRESSING 

Internet  addresses  are  four  byte  quantities,  stored  in  network  standard  format  (on  the  VAX  these 
are  word  and  byte  reversed).  The  include  file  <netinetjin.h>  defines  this  address  as  a  discrim* 
inated  union. 

Sockets  in  the  Internet  protocol  family  utilize  the  following  addressing  structure, 

struct  sockaddr.in  { 

short  sin^family; 
ujihort  8iD_port; 
struct  in_addr  sin_addr; 
char  sin_zero|8]; 

}; 

(Library  routmcB  to  returD  and  manipulate  structures  of  this  form  are  in  section  dN  of  the 
manual;  see  inlro(3N)  and  the  other  section  3  entries  mentioned  under  SEE  ALSO  below.)  Each 
socket  has  a  local  address  specifiable  in  this  form,  which  can  be  established  with  6md{2);  the  get- 
90ckname{2)  call  returns  this  address.  Each  socket  also  may  be  bound  to  a  peer  socket  with  an 
address  specified  in  this  form;  this  peer  address  can  be  specified  in  a  C0nntct{i)  call,  or  transiently 
with  a  single  message  in  a  9endio  or  stndmeg  call;  see  scnd(2).  The  peer  address  of  a  socket  is 
returned  by  the  gtiptername(2)  call. 

The  sin^addr  field  of  the  socket  address  specifies  the  Internet  address  of  the  machine  on  which  the 
socket  is  located.  A  special  value  may  be  specified  or  returned  for  this  field, 
8in_addr.8_addr»»=INADDR..ANY.  This  address  is  a  “wildcard”  and  matches  any  of  the  legal 
internet  addresses  on  the  local  machine.  This  address  is  useful  when  a  process  neither  knows  (nor 
cares)  what  the  local  Internet  address  is,  but  even  more  useful  for  server  processes  with  which  to 
service  all  requests  to. the  current  machine*  Since  a  machine  can  have  several  addresses  (one  per 
hardware  network  interface),  specifying  a  single  address  would  restrict  access  to  the  service  to 
those  clients  which  specified  the  address  of  that  interface.  By  specifying  INADDR_ANY»  the 
server  can  arrange  to  service  clients  from  all  interfaces. 

When  a  socket  address  is  bound,  the  networking  system  checks  that  there  is  an  interface  with  the 
address  specified  available  on  the  current  machine  (unless,  of  course,  a  wildcard  address  is 
specified),  and  returns  an  error  EADDRNOTAVAIL  if  no  such  interface  is  found. 

The  local  port  address  specified  in  a  (md(2)  call  is  restricted  to  be  greater  than 
IPPORT^RESERVED  (=1024,  in  <netmct/in.h>)  unless  the  creating  process  is  running  as  the 
super-user,  providing  a  space  of  protected  port  numbers.  The  local  port  address  is  also  required 
to  not  be  in  use  in  order  for  it  to  be  assigned.  This  is  checked  by  looking  for  another  socket  of 
the  same  type  which  has  the  same  local  address  and  local  port  number.  If  such  a  socket  already 
exists,  you  will  not  be  able  to  create  another  socket  at  the  same  address,  and  will  instead  get  the 
error  EADDRINUSE.  If  the  local  port  address  is  specified  as  0,  then  the  system  picks  a  unique 
por^  address  not  less  than  1PP0RT_RESERVED  and  assigns  it  to  the  port.  A  unique  local  port 
ad^lfcss  is  also  picked  for  a  socket  which  is  not  bound  but  which  is  used  with  connect(2)  or 
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8tndto{2)\  this  allows  <cp(4p)  connectioas  to  be  made  by  simply  doing  80cket{2)  and  then  con-^ 
ntct{2)  in  the  case  where  the  local  port  address  is  not  significant;  it  is  defaulted  by  the  system. 
Similarly  if  you  are  sending  datagrams  with  udp(4P)  and  do  not  care  which  port  they  come  from, 
you  can  just  do  8ocket{2)  and  8endto{2)  and  let  the  system  pick  a  port  number. 

Let  us  say  that  two  sockets  are  incompatible  if  they  have  the  same  port  number,  are  not  conected 
to  other  sockets,  and  do  not  have  different  local  host  addresses.  (It  is  possible  to  have  two  sockets 
with  the  same  port  number  and  different  local  host  addresses  because  a  machine  may  have  several 
local  addresses  from  its  different  network  interfaces.)  The  Internet  system  does  not  allow  such 
incompatible  sockets  to  exist  on  a  single  machine.  Consider  a  socket  which  has  a  specific  local 
host  and  local  port  number  on  the  current  machine.  If  another  process  tries  to  create  a  socket 
with  a  wildcard  local  host  address  and  the  same  port  number  then  that  request  will  be  denied. 
For  connection  based  sockets  this  prevents  these  two  sockets  from  attempting  to  connect  to  the 
same  foreign  host/ socket,  and  thereby  causing  great  havoc.  For  connectionless  sockets  this 
prevents  the  dilemma  which  would  result  from  trying  to  determine  who  to  deliver  an  incoming 
datagram  to  (since  more  than  one  socket  could  match  an  address  given  on  a  datagram).  The 
same  restriction  applies  if  the  wildcard  socket  exists  first.  (If  both  sockets  are  wildcard,  then  the 
normal  restrictions  on  duplicate  addresses  apply.) 

A  socket  option  SO^REUSEADDR  exists  to  allow  incompatible  sockets  to  be  created.  This 
option  is  needed  to  implement  the  File  Transfer  Protocol  (FTP)  which  requires  that  a  connection 
be  made  from  an  existing  port  number  (the  port  number  of  its  primary  connection)  to  a  different 
port  number  on  the  same  remote  host.  The  danger  here  is  that  the  user  would  attempt  to  con¬ 
nect  this  second  port  to  the  same  remote  host/port  that  the  primary  connection  was  using.  In 
using  SO JIEUSEADDR  the  user  is  pledging  not  to  do  this,  since  this  will  cause  the  first  connec¬ 
tion  to  abort. 

When  a  connect{2)  is  done,  the  Internet  system  first  checks  that  the  socket  is  not  already  con¬ 
nected.  If  does  not  allow  connections  to  port  number  0  on  another  host,  nor  does  it  allow  connec¬ 
tions  to  a  wildcard  host  (sin_addr.5_addr==INADDR_ANY);  attempts  to  do  this  yield  EAD- 
DR INUSE.  If  the  socket  from  which  the  connection  is  being  made  currently  has  a  wildcard  local 
address  (either  because  it  was  bound  to  a  specific  port  with  a  wildcard  address,  or  was  never  sub¬ 
jected  to  6ind(2)),  then  the  system  picks  a  local  Internet  address  for  the  socket  from  the  set  of 
addresses  of  interfaces  on  the  local  machine.  If  there  is  an  interface  on  the  local  machine  on  the 
same  network  as  the  machine  being  connected  to,  then  that  address  is  used.  Otherwise,  the 
^^first^’  local  network  interface  is  used  (this  is  the  one  that  prints  out  first  in  *^netstat  -i’^;  see 
ne^s^s^(8)).  Although  it  is  not  supposed  to  matter  which  interface  address  is  used,  in  practice  it 
would  probably  be  better  to  select  the  address  of  the  interface  through  which  the  packets  are  to 
be  routed.  This  is  not  currently  done  (as  it  would  involve  a  fair  amount  of  additional  overhead 
for  datagram  transmission). 

PROTOCOLS 

The  Internet  protocol  family  supported  by  the  operating  system  is  comprised  of  the  Internet 
Datagram  Protocol  (IP)  »p(4P),  Address  Resolution  Protocol  (ARP)  orp (4P),  Internet  Control 
Message  Protocol  (ICMP)  tcmp(4P),  Transmission  Control  Protocol  (TCP)  lcp(4P),  and  User 
Datagram  Protocol  (UDP)  urfp(4P). 

TCP  is  used  to  support  the  SOCK_STREAM  abstraction  while  UDP  is  used  to  support  the 
SOCK^DGRAM  abstraction.  A  raw  interface  to  IP  is  available  by  creating  an  Internet  socket  of 
type  SOCKJRAW;  see  tp(4P).  The  ICMP  message  protocol  is  not  directly  accessible,  and  is  used 
by  the  ^stem  to  handle  and  report  errors  in  protocol  processing.  The  ARP  protocol  is  used  to 
translate  32-bit  Internet  host  numbers  into  the  48  bit  addresses  needed  for  an  Ethernet. 

SEE  ALSO 

intro(3N),  byteorder(3N),  gethostent(3N),  getnetent(3N),  getprotoent(3N),  getservent(3N), 
inet(3N),  network(3N),  arp(4P),  tcp(4P),  udp(4P),  ip(4P) 

Internet  Protocol  Trandtion  Workbook,  Network  Information  Center,  SRI  (Sun  800-1056-01) 
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laternet  Protocol  Implementation  Guide,  Network  Information  Center,  SRI  (Son  800>1055-01) 
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NAME 

ip  -  Internet  Protocol 
SYNOPSIS 

None;  included  by  default  with  inel{4F). 

DESCRIPTION 

The  Internet  Protocol  is  designed  for  use  in  interconnected  qrstems  of  packet-switched  computer 
communication  networks.  It  provides  for  transmitting  blocks  of  data  called  datagrams  from 
sources  to  destinations,  where  sources  and  destinations  are  hosts  identified  by  fixed  length 
addresses.  It  also  provides  for  fragmentation  and  reassembly  of  long  datagrams,  if  necessary,  for 
transmission  through  “small  packet”  networks. 

IP  is  specifically  limited  in  scope.  There  are  no  mechanisms  to  augment  end-to-end  data  reliabil¬ 
ity,  flow  control,  sequencing,  or  other  services  commonly  found  in  host-to-host  protocols.  IP  can 
capitalize  on  the  services  of  its  supporting  networks  to  provide  various  types  and  qualities  of  ser¬ 
vice. 

IP  is  called  on  by  host-to-host  protocols,  including  tep{4P)  a  reliable  stream  protocol,  ttdp(4P)  a 
socket-socket  datagram  protocol,  and  Rd(4P)  the  network  disk  protocol.  Other  protocols  may  be 
layered  on  top  of  IP  using  the  raw  protocol  facilities  described  here  to  receive  and  send  datagrams 
with  a  specific  IP  protocol  number.  The  IP  protocol  calls  on  local  network  drivers  to  carry  the 
internet  datagram  to  the  next  gateway  or  destination  host. 

When  a  datagram  arrives  at  a  UNIX  host,  the  system  performs  a  checksum  on  the  header  of  the 
datagram.  If  this  fails,  or  if  the  datagram  is  unreasonably  short  or  the  header  length  specified  in 
the  datagram  is  not  within  range,  then  the  datagram  is  dropped.  (Checksumming  of  Internet 
datagrams  may  be  disabled  for  debugging  purposes  by  patching  the  kernel  variable  ipctaum  to 
have  the  value  0.) 

Next  the  ^stem  scans  the  IP  options  of  the  datagram.  Options  allowing  for  source  routing  (see 
ro«i»nj(4N))  and  also  the  collection  of  time  stamps  as  a  packet  folibws  a  particular  route  (for  net¬ 
work  monitoring  and  statistics  gathering  purposes)  are  handled;  other  options  are  ignored.  Pro¬ 
cessing  of  source  routing  options  may  result  in  an  UNREIACH  temj)(‘tf)  message  because  the 
source  routed  host  is  not  accessible. 

After  processing  the  options,  IP  checks  to  see  if  the  current  machine  is  the  destination  for  the 
datagram.  If  not,  then  IP  attempts  to  forward  the  datagram  to  the  proper  host.  Before  forward¬ 
ing  the  datagram,  IP  decrements  the  time  to  live  field  of  the  datagram  by  IPTTLDEC  seconds 
(currently  5  from  <netinet/ip.h>),  and  discards  the  datagram  if  its  lifetime  has  expired,  sending 
an  ICMP  TIMXCEED  error  packet  back  to  the  source  host.  Similarly  if  the  attempt  to  forward 
the  datagram  fails,  then  ICMP  messages  indicating  an  unreachable  network,  datagram  too  large, 
unreachable  port  (datagram  would  have  required  broadcasting  on  the  target  interface,  and  IP  does 
not  allow  directed  broadcasts),  lack  of  buffer  space  (reflected  as  a  source  quench),  or  unreachable 
host.  Note  however,  in  accordance  with  the  ICMP  protocol  specification,  ICMP  messages  are 
returned  only  for  the  first  fragment  of  fragmented  datagrams. 

It  is  possible  to  disable  the  forwarding  of  datagrams  by  a  host  by  patching  the  kernel  variable 
ipforwarding  to  have  value  0. 

If  a  packet  arrives  and  is  destined  for  this  machine,  then  IP  must  check  to  see  if  other  fragments 
of  the  same  datagram  are  being  held.  If  this  datagram  is  complete,  then  any  previous  fragments 
of  this  datagram  are  discarded.  If  this  is  only  a  fragment  of  a  datagram,  it  may  yield  a  complete 
set  of  pieces  for  the  datagram,  in  which  case  IP  constructs  the  complete  datagram  and  continues 
processing  with  that.  If  there  is  yet  no  complete  set  of  pieces  for  this  datagram  then  we  hold  onto 
as  piuch  data  as  we  have  received  (but  only  one  copy  of  each  data  byte  from  the  datagram)  in 
hopes  that  the  rest  of  the  pieces  of  the  fragmented  datagram  will  arrive  and  we  will  be  able  to 
proceed.  We  allow  IPFRAGTTL  (currently  15  in  <netinet/ip.h>)  seconds  for  all  the  fragments 
of  a  datagram  to  arrive,  and  discard  partial  fragments  then  if  the  datagram  has  not  yet  been 
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completely  assembled. 

When  we  have  a  complete  input  datagram  it  is  passed  out  to  the  appropriate  protocol’s  input  rou¬ 
tine:  either  ^cp(4P),  udp(4P),  urf(4P),  »cmp(4P)  or  a  user  process  through  a  raw  IP  socket  as 
described  below. 

Datagrams  are  output  by  the  system  implemented  protocols  <cp (4P),  udp (4P),  n(f(4P),  and 
icmp(4P)  as  well  as  by  packet  forwarding  operations  and  user  processes  through  raw  IP  sockets. 
Output  packets  are  normally  subjected  to  routing  as  described  in  r<7ti^m^(4N);  special  processes 
such  as  the  routing  daemon  rouitd{ZC)  occasionally  use  the  SOJDONTROUTE  socket  option  to 
cause  the  p2tcket8  to  avoid  the  routing  tables  and  go  directly  to  the  network  interface  which  has 
the  same  network  number  as  the  packet  is  addressed  to.  This  is  used  to  be  able  to  test  the  ability 
of  the  hardware  to  transmit  and  receive  packets  even  when  we  believe  that  the  hardware  is  bro¬ 
ken  and  have  therefore  deleted  it  from  the  routing  tables. 

If  there  is  no  route  to  a  destination  address  or  if  the  SOJDONTROUTE  option  is  given  and  there 
is  no  interface  on  the  network  specified  by  the  destination  address,  then  the  IP  output  routine 
returns  a  ENETUNREACH  error.  (This  and  the  other  IP  output  errors  are  reflected  back  to  user 
processes  through  the  various  protocols,  which  individually  describe  how  errors  are  reported.) 

In  the  (hopefully  normal)  case  where  there  is  a  suitable  route  or  network  interface,  the  destination 
address  is  checked  to  see  if  it  specifies  a  broadcast  (address  INADDR_ANY;  see  mel(4F));  if  it 
does,  and  the  hardware  interface  does  not  support  broadcasts,  then  an  EADDR  NOT  AVAIL  is 
returned;  if  the  caller  is  not  the  super-user  then  a  EACCESS  error  will  be  returned.  IP  also  does 
not  allow  broadcast  messages  to  be  fragmented,  returning  a  EMSGSIZE  error  in  this  case. 

If  the  datagram  passes  all  these  tests,  and  is  small  enough  to  be  sent  in  one  chunk,  then  the  sys¬ 
tem  calls  the  output  routine  for  the  particular  hardware  interface  to  transmit  the  packet.  The 
interface  may  give  an  error  indication,  which  is  reflected  to  IP  output’s  caller;  see  the  various 
interface’s  documentation  for  a  description  of  the  errors  which  they  may  encounter.  If  a 
datagram  is  to  be  fragmented,  it  may  have  the  IPJDF  (don’t  fragment)  flag  set  (although 
currently  this  can  happen  only  for  forwarded  datagrams).  If  it  does,  then  the  datagram  will  be 
rejected  (and  result  in  an  ICMP  error  datagram).  If  the  system  runs  out  of  buffer  space  in  frag¬ 
menting  a  datagram  then  a  ENOBUFS  error  will  be  returned. 

IP  provides  a  space  of  255  protocols.  The  known  protocols  are  defined  in  <net!net/m.h>.  The 
ICMP,  TCP,  UDP  and  ND  protocols  are  processed  internally  by  the  i^stem;  others  may  be 
accessed  through  a  raw  socket  by  doing: 

0  =  0ocket(AP  JNET,  SOCK.RAW,  IPPROTO.xxx); 

Datagrams  sent  from  this  socket  will  have  the  current  host’s  address  and  the  specified  protocol 
number;  the  raw  IP  driver  will  construct  an  appropriate  header.  When  IP  datagrams  are  received 
for  this  protocol  they  are  queued  on  the  raw  socket  where  they  may  be  read  with  recvfrom;  the 
source  IP  address  is  reflected  in  the  received  address. 

SEE  ALSO 

8end(2),  recv(2),  inet(4F) 

Internet  Protocol,  RFC791,  USC-ISI  (Sun  800-1063-01) 

BUGS 

One  should  be  able  to  send  and  receive  IP  options. 

Raw  sockets  should  receive  ICMP  error  packets  relating  to  the  protocol;  currently  such  packets 
are  simply  discarded. 
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NAME 

ip  -  Disk  driver  for  Interphase  2180  SMD  Disk  Controller 
SYNOPSIS 

controller  IpcO  at  mbO  csr  0x40  priority  2 
disk  ipO  at  ipcO  drive  0 
disk  ipl  at  ipcO  drive  1 

DESCRIPTION 

Files  with  minor  device  numbers  0  through  7  refer  to  various  portions  of  drive  0;  minor  devices  8 
through  15  refer  to  drive  1,  and  so  on.  The  standard  device  names  begin  with  '‘ip’*  followed  by 
the  drive  number  and  then  a  letter  a-h  for  partitions  0-7  respectively.  The  character  ?  stands 
here  for  a  drive  number  in  the  range  0-7. 

The  block  file’s  access  the  disk  via  the  system’s  normal  buffering  mechanism  and  may  be  read  and 
written  without  regard  to  physical  disk  records.  There  is  also  a  ‘raw’  interface  which  provides  for 
direct  transmission  between  the  disk  and  the  user’s  read  or  write  buffer.  A  single  read  or  write 
call  results  in  exactly  one  I/O  operation  and  therefore  raw  I/O  is  considerably  more  effficient 
when  many  words  are  transmitted.  The  names  of  the  raw  files  conventionally  begin  with  an  extra 
‘r.’ 

In  raw  I/O  counts  should  be  a  multiple  of  512  bytes  (a  disk  sector).  Likewise  seek  calls  should 
specify  a  multiple  of  512  bytes. 

DISK  SUPPORT 

This  driver  handles  all  SMD  drives,  by  reading  a  label  from  sector  0  of  the  drive  which  describes 
the  disk  geometry  and  partitioning. 

The  ip?a  partition  is  normally  used  for  the  root  file  system  on  a  disk,  the  ip?b  partition  as  a  pag¬ 
ing  area,  and  the  ip?c  partition  for  pack-pack  copying  (it  normally  maps  the  entire  disk).  The 
rest  of  the  disk  is  normally  the  ip?h  partition. 

FILES 

/dev/ip[0-7]Ia-h]  block  files 

/ dev  /rip[0-7|  [a-h]  raw  files 

SEE  ALSO 

dkio(4S),  xy(4S) 

“Interphase  SMD2180  Storage  Module  Controller/Formatter  -  User’s  Guide”  (Sun  800-0274) 
DIAGNOSTICS 

ip%dt  SMD-2180.  When  booting  tells  the  controller  type. 

lp%dt  initialization  failed.  Because  the  controller  didn’t  respond;  perhaps  another  device  is  at 
the  address  the  system  expected  an  Interphase  controller  at. 

ip%d:  error  %x  reading  label  on  head  %d.  Error  reading  drive  geometiy /partition  table 
information. 

ip%ds  Corrupt  label  on  head  %d.  The  geometry /partition  label  checksum  was  incorrect. 

lp%dt  Misplaced  label  on  head  %d.  A  disk  label  was  copied  to  the  wrong  head  on  the  disk; 
shoudn’t  happen. 

ip%dt  Unsupported  phys  partition  #  %d.  This  indicates  a  bad  label. 

\p%di  unit  not  online, 

lp%d%cx  cmd  how  (msg)  blk  %d,  A  command  such  as  read,  write,  or  format  encountered  a 
error  condition  (how):  either  it  failed,  the  unit  was  restored,  or  an  operation  was  re^rj^ed.  The 
meg  is  derived  from  the  error  number  given  by  the  controller,  indicating  a  condition  such  as 
“drive  not  ready”,  “sector  not  found”  or  “disk  write  protected”. 
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BUGS 

In  raw  I/O  read  and  write{2)  truncate  file  offsets  to  512-byte  block  boundaries,  and  write  scribbles 
on  the  tail  of  incomplete  blocks.  Thus,  in  programs  that  are  likely  to  access  raw  devices,  read, 
write  and  t8eet(2)  should  always  deal  in  512>byte  multiples. 

The  driver  no  longer  supports  versions  of  the  2181. 


o 
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NAME 

kb  -  Sun  keyboard 

SYNOPSIS 

paeudo-device  kb3 

DESCRIPTION 

Kb  provides  access  to  the  Sun  workstation  keyboard  translation.  Definitions  for  alterring  key¬ 
board  translation  are  in  <8undev/kbi0.b>  and  <8ttndev/kbd.h>. 

The  call  KIOCTRANS  controls  the  presence  of  keyboard  translation: 
int  x; 

err  =  ioctl(fd,  KIOCTRANS,  Sex); 

where  if  2  is  0  the  keyboard  tranlation  is  turned  off  and  up/down  key  codes  are  reported.  Speci¬ 
fying  z  as  1  restores  normal  keyboard  translations. 

The  call  KIOCSETKEY  changes  a  keyboard  translation  table  entry: 
struct  kiockey  { 

int  kio_tablemask;  /*  Translation  table  (one  of:  0,  CAPSMASK, 

SHIFTMASK,  CTRLMASK,  UPMASK)  •/ 
u_cbar  kio_station;  /*  Physical  keyboard  key  station  (O-IS?)  */ 
u_char  kio_entiy;  /*  Translation  table  station’s  entry  */ 
char  kio_8tring(10];  /*  Value  for  STRING  entries  (null  terminated)  */ 

}; 


struct  kiockey  key; 

err  =  ioctl(fd,  KIOCSETKEY,  &key); 

Set  kiojablematk  table’s  kio_8(ation  to  tio_en(rff.  Copy  kio_8tring  to  string  table  if  kio_entry  is 
between  STRING  and  STRING+  IS.  This  call  may  return  EINVAL  if  there  are  invalid  argu¬ 
ments. 

The  call  KIOCGETKEY  determines  the  current  value  of  a  keyboard  translation  table  entry: 
struct  kiockey  key; 

err  »  ioctl(fd,  KIOCGETKEY,  &key); 

Get  kiojlablemaek  table’s  kiojttation  to  kio_entrjf.  Get  kio_»tring  from  string  table  if  kio^entry  is 
between  STRING  and  STRING-1- 15.  This  call  may  return  EINVAL  if  there  are  invalid  argu¬ 
ments. 


FILES 

/dev/kbd 

SEE  ALSO 

kbd(5) 
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NAME 

lo  -  software  loopback  network  interface 

SYNOPSIS 

paeudo-device  loop 

DESCRIPTION 

The  loop  device  is  a  software  loopback  network  interface;  see  iy(4N)  for  a  general  description  of 
network  interfaces. 

The  loop  interface  is  used  for  performance  analysis  and  software  testing^  and  to  provide 
guaranteed  access  to  Internet  protocols  on  machines  with  no  local  network  interfaces.  A  typical 
application  is  the  comsa^{8C)  server  which  accepts  notification  of  mail  delivery  through  a  particu¬ 
lar  port  on  the  loopback  interface. 

By  default,  the  loopback  interface  is  accessible  at  Internet  address  127.0.0.1  (non-standard);  this 
address  may  be  changed  with  the  SIOCSIPADDR  ioctl. 

DIAGNOSTICS 

lo%ds  ean*t  handle  af%d.  The  interface  was  handed  a  message  with  addresses  formatted  in  an 
unsuitable  address  family;  the  packet  was  dropped. 

SEE  ALSO 

if(4N),  inet(4F) 

BUGS 

It  should  handle  all  address  and  protocol  families.  An  approved  network  address  should  be 
reserved  for  this  interface. 
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NAME 

mb  -  Multibus 
SYNOPSIS 

controller  mbO  at  nexus  f 
DESCRIPTION 

The  mh  device  is  the  driver  for  the  Intel  Multibus(R)»  which  provides  support  functions  to  the 
various  devices  which  can  reside  there.  It  vectors  interrupts  to  the  Multibus  devices  according  to 
the  priority  level  of  the  interrupt  received  and  queues  requests  for  dma  when  there  are  insufficient 
resources  to  service  the  request  or  to  allow  certain  dma*s  to  proceed  exclusively.  It  also  imple* 
meats  byte  swapping  to/from  deficient  devices. 

DIAGNOSTICS 

None. 

SEE  ALSO 

ar(4S),  cg(4S),  ip(4S),  in8(4S),  oct(4S),  tm(4S),  vp(4S),  xy(4S),  zs(4S) 

Intel  Multibus(R)  Specification^  Order  Number  9800^3-04  (Sun  800>1057-01) 
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NAME 

mem,  kmem,  mbmem,  mbio  -  main  memory  and  I/O  space 
SYNOPSIS 

None;  included  with  standard  system, 

DESCRIPTION 

These  devices  are  special  files  that  map  memory  and  bus  i/o  space.  They  may  be  read, 
seek’ed  and  (except  for  kmem)  mmap(2)ed. 

Mem  is  a  special  file  that  is  an  image  of  the  physical  memory  of  the  computer.  It  may 
for  example,  to  examine  (and  even  to  patch)  the  system. 

Kmem  is  a  special  file  that  is  2ui  image  of  the  kernel  virtual  memory  of  the  system. 

Mbmem  is  a  special  file  that  is  an  image  of  the  Multibus  memory  of  the  system.  Multibus 
memory  is  in  the  range  from  0  to  1  Megabyte. 

Mbio  is  a  special  file  that  is  an  image  of  the  Multibus  I/O  space.  Multibus  I/O  space  extends 
from  0  to  64K. 

When  reading  and  writing  mbmem  and  mbio  odd  counts  or  offsets  cause  byte  accesses  and  even 
counts  and  offsets  cause  word  accesses. 

DIAGNOSTICS 

None. 

FILES 

/dev/mem 
/dev /kmem 
/dev/mbmem 
/dev/mbio 


written, 
be  used, 
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NAME 

mouse  -  Sun  mouse 

SYNOPSIS 

pseudo^^dev'iee  ms3 

DESCRIPTION 

The  mouse  interface  provides  access  to  the  Sun  Workstation  mouse. 

The  mouse  incorporates  a  microprocessor  which  generates  a  byte-stream  protocol  encoding  mouse 
motions. 

Each  mouse  sample  in  the  byte  stream  consists  of  three  bytes:  the  first  byte  gives  the  button  state 
with  value  0x87piuL  where  but  is  the  low  three  bits  giving  the  mouse  buttons,  where  a  0  (zero) 
bit  means  that  a  button  is  pressed,  and  a  1  (one)  bit  means  a  button  is  not  pressed.  Thus  if  the 
left  button  is  down  the  value  of  this  sample  is  Qx83,  while  if  the  right  button  is  down  the  byte  is 
0x86. 

The  next  two  bytes  of  each  sample  give  the  z  and  y  delta's  of  this  sample  as  signed  bytes.  The 
mouse  uses  a  lower-left  coordinate  system,  so  moves  to  the  right  on  the  screen  yield  positive  z 
values  and  moves  down  the  screen  yield  negative  y  values. 

The  beginning  of  a  sample  is  identifiable  because  the  delta's  are  constrained  to  not  have  values  in 
the  range  (^80-0x87. 

FILES 

/dev/mouse 

SEE  ALSO 

win(4S) 

Mouse  System  Mouse  Manual  (Sun  80(M1419) 

User’s  Guide  for  the  Sun  Workstation  Mouse  Subt^stem  (Sun  800-0402) 
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NAME 

mti  -  Systech  MTL800/1600  multi-teiminal  interface 
SYNOPSIS 

device  mtIO  at  mbO  etr  0x620  flags  Oxflff  priority  4 

DESCRIPTION 

The  Systech  MTI  card  provides  8  (MTI-800)  or  16  (MTI-1600)  serial  communication  lines  with 
modem  control.  Each  line  behaves  as  described  in  i/y(4).  Input  and  output  for  each  line  may 
independently  be  set  to  run  at  any  of  16  speeds;  see  Wi/(4)  for  the  encoding. 

Bit  I  of  flags  may  be  specified  to  say  that  a  line  is  not  properly  connected,  and  that  the  line  » 
should  be  treated  as  hard-wired  with  carrier  always  present.  Thus  specifying  “flags  0x0004”  in 
the  specification  of  mtiO  would  cause  line  tty02  to  be  treated  in  this  way . 

To  allow  a  single  tty  line  to  be  connected  to  a  modem  and  used  for  both  incoming  and  outgoing 
calls,  a  special  feature,  controlled  by  the  minor  device  number,  has  been  added.  Minor  device 
numbers  in  the  range  0-127  correspond  directly  to  the  normal  tty  lines  and  are  named  tt]/*. 
Minor  device  numbers  in  the  range  128  -  256  correspond  to  the  same  physical  lines  as  those  above 
(i.e.  the  same  line  as  the  minor  device  number  minus  128)  and  are  (conventionally)  named  cua*. 
The  cu«  lines  are  special  in  that  they  can  be  opened  even  when  there  is  no  carrier  on  the  line. 
Once  a  c«o  line  is  opened,  the  corresponding  tty  line  can  not  be  opened  until  the  cuo  line  is 
closed.  Also,  if  the  tty  line  has  been  opened  successfully  (usually  only  when  carrier  is  recognized 
on  the  modem)  the  corresponding  cua  line  can  not  be  opened.  This  allows  a  modem  to  be 
attached  to  /det>/«i/d0  (usually  renamed  to  fdcvIttydO)  and  used  for  dialin  (be  enabling  the  line 
for  login  in  leteftlya)  and  also  used  for  dialout  (by  <»p(lC)  or  uucp(lC))  as  f  devf  cuaO  when  no  one 
is  logged  in  on  the  line.  Note  that  the  bit  in  the  flags  word  in  the  config  file  (see  above)  must  be 
zero  for  this  line. 

WIRING 

The  Systech  requires  the  GTS  modem  control  signal  to  operate.  If  the  device  does  not  supply 
CTS  then  RTS  should  be  jumpered  to  GTS  at  the  distribution  panel.  Also,  the  GD  (carrier 
detect)  line  does  not  work  properly.  When  connecting  a  modem,  the  modem’s  CD  line  should  be 
wired  to  DSR,  which  the  software  will  treat  as  carrier  detect. 

FILES 

/dev/tty0(0-9a-fl  hardwired  tty  lines 
/dev/tlyd[0-9a-fi  dialin  tty  lines 
/dev/cua[0-9a'f]  dialout  tty  lines 

SEE  ALSO 

tty(4),  zs(4S) 

DIAGNOSTICS 

Most  of  these  diagnostics  “should  never  happen”  and  their  occurrence  usually  indicates  problems 
elsewhere  in  the  system. 

mtl%d,%di  tUo  overflow.  More  than  512  characters  have  been  received  by  the  mti  hardware 
without  being  read  by  the  software.  Extremely  unlikely  to  occur. 

intl%di  error  %x.  The  mti  returned  the  indicated  error  code.  See  the  mti  manual. 
intl%dt  DMA  output  error.  The  mti  encountered  an  error  while  trying  to  do  DMA  output. 

mtl^di  Impossible  response  %x»  The  mti  returned  of  flags  may  be  specified  to  say  that  a  line 
is  not  From  martyOufo  Sat  Feb  25  16:04:52  1984 
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NAME 

mtio  -  UNIX  magnetic  tape  interface 
SYNOPSIS 

^include  <8ys/ioctl.h> 

^include  <^8/mtio.h> 

DESCRIPTION 

The  files  mtO,  refer  to  the  UNIX  magtape  drives,  which  read  and  write  magnetic  tape  in 

2048  byte  blocks.  (The  2048  is  actually  BLKDEVJOSIZE  in  <^8/param.h>.)  The  following 
description  applies  to  any  of  the  transport/controller  pairs.  The  files  mtO,  tniS  and  miS, 
mill  are  rewound  when  closed;  the  others  are  not.  When  a  file  open  for  writing  is  closed,  two 
end-of-files  are  written.  If  the  tape  is  not  to  be  rewound  it  i$  positioned  with  the  head  between 
the  two  tapemarks. 

The  mt  files  discussed  above  are  useful  when  it  is  desired  to  access  the  tape  in  a  way  compatible 
with  ordinary  files.  When  foreign  tapes  are  to  be  dealt  with,  and  especially  when  long  records  are 
to  be  read  or  written,  the  'raw*  interface  is  appropriate.  The  associated  files  are  named  rmtO, 
rmilS,  but  the  same  minor-device  considerations  as  for  the  regular  files  still  apply.  A  number  of 
other  ioctl  operations  are  available  on  raw  magnetic  tape.  The  following  definitions  are  from 
<sys/mtio.h>: 

/* 

*  Structures  and  definitions  for  mag  tape  fo  control  commands 

V 


f*  structure  for  MTIOCTOP 
struct  mtop  { 

short  mt_op; 
daddr_t  mt jcount; 

}; 


/*  operations  */ 

#define  MTWEOF  0 

#define  MTFSF  1 

#define  MTBSF  2 

#define  MTFSR  3 

#define  MTBSR  4 

#define  MTREW  5 

#deflne  MTOFFL  6 

#deflne  MTNOP  7 


mag  tape  op  command 

/*  operations  defined  below  */ 
/♦  how  many  of  them  */ 


/*  write  an  end-of-file  record  */ 

/*  forward  space  file  */ 

/*  backward  space  file  */ 

/*  forward  space  record 
/*  backward  space  record  */ 

/*  rewind  */ 

/*  rewind  and  put  the  drive  offline  */ 
/♦  no  operation,  sets  status  only  ♦/ 


/♦  structure  for  MTIOCGET  -  mag  tape  get  status  command  *f 


struct  mtget  { 

short  mtjtype;  /*  type  of  magtape  device 

the  following  two  registers  are  grossly  device  dependent  ♦/ 
short  mt^dsreg;  /*  “drive  status”  register  */ 

short  mt.erreg;  /’•“  “error”  register 

/*  end  device-dependent  registers  */ 

short  mt^resid;  residual  count  */ 

/*  the  following  two  are  not  yet  implemented 

daddr_tmt_fileno;  file  number  of  current  position  ♦/ 

daddr_tmt_blkno;  /*  block  number  of  current  position  */ 
/*  end  not  yet  implemented  */ 

}; 
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/• 

*  Constants  for  mt.type  byte 

V 

#defineMTJSTS  0x01 

#defineMT  ISHT  0x02 

#deflneMT_ISTM  0x03 

#defineMTJSMT  0x04 

#defineMTJSUT  0x05 

#deflneMTJSCPC  0x08 

#deflneMTJSAR  0x07 


/*  vax:  unibuB  ts-11  */ 

/*  vax:  masebus  tu77,  etc  */ 

/*  vax:  anibus  tm-ll  */ 

I*  vax:  tnassbus  tu78  */ 

/*  vax:  unibus  gcr  */ 

f*  sun:  Multibus  tapemaster  */ 

/*  sun:  Multibus  archive  */ 


/*  mag  tape  io  control  commands  */ 

#deflne^MTIOCTOP  _IOW(m,  1,  struct  mtop)  /*  do  a  mag  tape  op  */ 

#deflne  MTIOCQET  _IOR(m,  2,  struct  mtget)  /*  get  tape  status  */ 

#ifndef  KERNEL 

#defineDEFTAPE  ’’/dev/rmtl2" 

#endif 

Each  read  or  writt  call  reads  or  writes  the  next  record  on  the  tape.  In  the  write  case  the  record 
has  the  same  length  as  the  buffer  given.  During  a  read,  the  record  size  is  passed  back  as  the 
number  of  bytes  read,  provided  it  is  no  greater  than  the  buffer  size.  In  raw  tape  I/O  seeks  are 
ignored.  A  zero  byte  count  is  returned  when  a  tape  mark  is  read,  but  another  read  will  fetch  the 
first  record  of  the  new  tape  file. 

FILES 

/dev/mt? 

/dev/rmt? 

/dev/rar? 

SEE  ALSO 

mt(l),  tar(l),  ar(4S),  tm(4S) 
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NAME 

nd  -  network  disk  driver 

SYNOPSIS 

pseudoodevice  nd 

DESCRIPTION 

The  network  disk  device,  Idtvfn^,  allows  a  client  workstation  to  perform  disk  10  operations  on  a 
server  system,  over  the  network.  To  the  client  ^stem,  this  device  looks  like  any  normal  disk 
driver:  it  allows  read/write  operations  at  a  given  block  number  and  byte  count.  Note  that  this 
provides  a  network  disk  block  access  service  rather  than  a  network  file  access  service. 

Typically  the  client  ^stem  will  have  no  disks  at  all.  In  this  case  fdevl  ndO  contains  the  client*s 
root  file  system  (including  /usr  files),  and  ndl  is  used  as  a  paging  area.  Client  access  to  these  dev¬ 
ices  is  converted  to  net  disk  protocol  requests  and  sent  to  the  server  system  over  the  network. 
The  server  receives  the  request,  performs  the  actual  disk  lO,  and  sends  a  response  back  to  the 
client. 

The  server  contains  a  table  which  lists  the  net  address  of  each  of  his  clients  and  the  server  disk 
partition  which  corresponds  to  each  client  unit  number  (ndO,l,,..).  This  table  resides  in  the  server 
kernel  in  a  structure  owned  by  the  nd  device.  The  table  is  initialized  by  running  the  program 
/tic/nd  with  text  file  (etcfndJocal  as  its  input,  fetcfnd  then  issues  ioctl{i)  functions  to  load  the 
table  into  the  kernel. 

In  addition  to  the  read/write  units  there  are  public  read-only  units  which  are  named 

jdevjndp*.  The  correspondence  to  server  partitions  is  specified  by  the  IttcjndAocal  text  file,  in  a 
similar  manner  to  the  private  partitions.  The  public  units  can  be  used  to  provide  shared  access  to 
binaries  or  libraries  (/bin,  /usr/bin,  /usr/ucb,  /usr/lib)  so  that  each  diskless  client  does  not  have 
to  waste  space  in  his  private  partitions  for  these  files.  This  is  done  by  providing  a  public  file  sys¬ 
tem  at  the  server  (  jdevfndpO  )  which  is  mounted  on  of  each  diskless  client.  The  clients 

then  use  symbolic  links  to  read  the  public  files:  /bin  ->  /pub/bin,  /usr/ucb  ->  /pub/usr/ucb. 
One  requirement  in  this  case  is  that  the  server  (who  has  read/write  access  to  this  file  system) 
should  not  perform  write  activity  with  any  public  filesystem.  This  is  because  each  client  is  locally 
cacheing  blocks. 

One  last  type  of  unit  is  provided  for  use  by  the  server  These  are  called  local  units  and  are 
named  fdevfnd^.  The  Sun  physical  disk  sector  0  label  only  provides  a  limited  number  of  parti¬ 
tions  per  physical  disk  (eight).  Since  this  number  is  small  and  these  partitions  have  somewhat 
fixed  meanings,  the  nd  driver  itself  has  a  subpartitioning  capability  builMn.  This  allows  the  large 
server  physical  disk  partition  (e.g.  fdevfxyOg  )  to  be  broken  up  into  any  number  of  diskless  client 
partitions.  Of  course  on  the  client  side  these  would  be  referenced  as  jdevfndO,!,.,,  ;  but  the 
server  needs  to  reference  these  client  partitions  from  time  to  time,  to  do  mk/s(8)  and  fsck{S)  for 
example.  The  fdevjndf^  entries  allow  the  server  'local*  access  to  his  subpartitions  without  causing 
any  net  activity.  The  actual  local  unit  number  to  client  unit  number  correspondence  is  again 
recorded  in  the  jetcIndAocal  text  file. 

The  nd  device  driver  is  the  same  on  both  the  client  and  server  sides.  There  are  no  user  level 
processes  associated  with  either  side,  thus  the  latency  and  transfer  rates  are  close  to  maximal. 

The  minor  device  an<i  ioctl  encoding  used  is  given  in  file  <sun/nrf»o.A>.  The  low  six  bits  of  the 
minor  number  are  the  unit  number.  The  0ix40  bit  indicates  a  public  unit;  the  0x80  bit  indicates  a 
local  unit. 

INITIALIZATION 

No  special  initialization  is  required  on  the  client  side;  he  finds  the  server  by  broadcasting  the  ini¬ 
tial  request.  Upon  getting  a  response,  he  locks  onto  that  server  address. 

At  the  server,  the  nd(8c)  command  initializes  the  network  disk  service  by  issuing  ioctFs  to  the 
kernel. 
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ERRORS 

Generally  physical  disk  10  errors  detected  at  the  server  are  returned  to  the  client  for  action.  If 
the  server  is  down  or  unaccessable,  the  client  will  see  the  console  message  file  server  not  respond¬ 
ing:  still  trying.  The  client  continues  (forever)  making  his  request  until  he  gets  positive  ack¬ 
nowledgement  from  the  server.  This  means  the  server  can  crash  or  power  down  and  come  back 
up  without  any  special  action  required  of  the  user  at  the  client  machine.  It  also  means  the  pro¬ 
cess  performing  the  lO  to  nd  will  block,  insensitive  to  signals,  since  the  process  is  sleeping  inside 
the  kernel  at  PRIBIO. 


PROTOCOL  AND  DRIVER  INTERNALS 

The  protocol  packet  is  defined  in  <sunfndio.h>  and  also  included  below; 


/* 

*  hid’  protocol  packet  format. 

V 

struct  ndpack  { 

struct  ip  np^lpi  /* 

u_ehar  npjopi  /♦ 

ujehar  ttpjmlni  /* 

char  npjerrori  /* 

char  npjveri  /♦ 

long  np.seqi  /* 

long  npjblknoi  /* 

long  npjbcounti  /* 

long  npjresld} 
long  npjcaddri  /* 

long  npjccounti  /* 

}»  /• 


Ip  header,  proto  IPPROTO.ND  */ 
operation  code,  see  below  */ 
minor  device 
bjsrror  */ 
version  number 
sequence  number 
bjblkno,  disk  block  number  */ 
bjbcountf  byte  count 
b^resid,  residual  byte  count  */ 
current  byte  ofbei  of  this  padret 
current  byte  count  of  thb  packet  */ 
data  follows  */ 


/♦  np.op  operation  codes.  */ 


#defln«  NDOPRBAD 

1 

/*  read  */ 

#deflne  NDOPWRITE 

S 

/*  write  */ 

#ddlne  NDOPERROR 

z 

/*  error  */ 

#della«  NDOPCODB 

7 

/*  op  code  mask  */ 

#deOn«  NDOPWAIT 

010 

/*  waiting  for  DONE  or  next  request  */ 

#d«lln.  NDOPDONE 

oso 

/*  operation  done  */ 

/*  mine  protocol  defines. 

#deflne  NDMAXDATA 

1024 

/*  max  data  per  packet  */ 

#d.fln.  NDMAXIO 

53*1024  /*  max  npjbcount  */ 

IP  datagrams  were  chosen  instead  of  UDP  datagrams  because  only  the  IP  header  is  checksummed, 
not  the  entire  packet  as  in  UDP.  Also  the  kernel  level  interface  to  the  IP  layer  is  simpler.  The 
mm,  btkno,  and  beount  fields  are  copied  directly  from  the  client’s  strategy  request.  The  sequence 
number  field  seq  is  incremented  on  each  new  client  request  and  is  matched  with  incoming  server 
responses.  The  server  essentially  echos  the  request  header  in  his  responses,  altering  certain  fields. 
The  eaddr  and  ecount  fields  show  the  current  byte  address  and  count  of  the  data  in  this  packet,  or 
the  data  expected  to  be  sent  by  the  other  side. 

The  protocol  is  very  simple  and  driven  entirely  from  the  client  side.  As  soon  as  the  client  ndstrar 
tegy  routine  is  called,  the  request  is  sent  to  the  server;  this  allows  disk  sorting  to  occur  at  the 
server  as  soon  as  possible.  Transactions  which  send  data  (client  writes  on  the  client  side,  client 
reads  on  the  server  side)  can  only  send  a  set  number  of  packets  of  NDMAXDATA  bytes  each, 
before  waiting  for  an  acknowledgement.  The  defaults  are  currently  set  at  6  packets  of  IK  bytes 
each;  the  NDIOCETHER  ioctl  allows  setting  this  value  on  the  server  side.  This  allows  the 


Sun  Releasft  1.1 


Last  change:  20  March  1084 


37 


ND(4P) 


SPECIAL  FILES 


ND(4P) 


normal  4K  byte  case  to  occur  with  just  one  ‘transaction’.  The  NDOPWAIT  bit  is  set  in  the  op 
field  by  the  sender  to  indicate  he  will  send  no  more  until  acknowledged  (or  requested)  by  the 
other  side.  The  NDOPDONE  bit  is  set  by  the  server  side  to  indicate  the  request  operation  has 
completed;  for  both  the  read  and  write  cases  this  means  the  requested  disk  10  has  actually 
occured. 

Requests  received  by  the  server  are  entered  on  an  active  list  which  is  timed  out  and  discarded  if 
not  completed  within  NDXTIMER  seconds.  Requests  received  by  the  server  allocate  a  bcounl  size 
buffer  to  minimize  buffer  copying.  Contiguous  DMA  disk  lO  thus  occurs  in  the  same  size  chunks 
it  would  if  requested  from  a  local  physical  disk. 

BOOTSTRAP 

The  Sun  workstation  has  PROM  code  to  perform  a  net  boot  using  this  driver.  Usually,  the  boot 
files  are  obtained  from  public  device  0  (/dev/ndpO)  on  the  server  with  which  the  client  is 
registered;  this  allows  multiple  servers  to  exist  on  the  same  net  (even  running  different  releases  of 
kernel  and  boot  software).  If  the  station  you  are  booting  is  not  registered  on  any  of  the  servers, 
you  will  have  to  specify  the  hex  Internet  host  number  of  the  server  in  the  boot  command  string 
(e.g.):  ‘bec(0,5,0)vmunix'. 

This  booting  performs  exactly  the  same  steps  involved  in  a  real  disk  boot  which  are: 

1)  user  types  ‘b’  to  PROM  monitor. 

2)  PROM  loads  blocks  1  thru  15  of  /dev/ndpO  (bootpr). 

3)  bootnd  loads  ‘/boot’. 

4)  /boot  loads  ‘/vmunix’. 

SEE  ALSO 

ioctl(2),  nd(8C) 

BUGS 

The  operations  described  in  dkio{4)  are  not  supported. 

The  local  host’s  disk  buffer  cache  is  not  used  by  network  disk  access.  This  means  that  if  either  a 
local  host  or  a  remote  host  is  writing,  the  changes  will  be  visible  at  random  based  on  the  cache  hit 
frequency  on  the  local  host.  If  both  the  local  and  remote  hosts  are  writing  to  the  same  filesystem, 
one  machine’s  changes  can  be  randomly  lost,  based  again  on  cache  hit  and  deferred  write  timings. 

If  an  R/O  remote  file  system  is  mounted  R/W  by  mistake,  it  is  impossible  to  umount  it. 
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NAME 

null  -  data  sink 
SYNOPSIS 

Non«;  included  with  standard  system. 

DESCRIPTION 

Data  written  on  a  null  special  file  is  discarded. 

Reads  from  a  null  special  file  always  return  an  end^of-file  indication. 

FILES 

/dev /null 
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NAME 

oct  -  Central  Data  octal  serial  card 
SYNOPSIS 

device  oetO  at  mbO  eer  0x620  flaga  Oicff  priority  4 
DESCRIPTION 

The  Central  Data  card  provides  8  serial  communication  lines  witb  modem  control.  Each  line 
behaves  as.  described  in  Input  and  output  for  each  tme  may  mdependently  be  set  to  run  at 

any  of  16  speeds;  see  fly(4]^  for  the  encoding. 

Bit  f  of  Sags  may  be  speciDed  to  say  that  a  line  is  not  properly  connected,,  and  that  the  line,  i 
should  be  treated  as  hard-wired  with  carrier  always  present.  Thus  specifying  **flag8  0x0004”  in 
the  specification  ofbctO  would  cause  line  ttym2  to  be  treated  b  this  way. 

PILES 

/dev/t^  ^nnoJjO-Oa-lf 

/dev/ttyd^Oap^ 

SEEALSO 

tty(4^Z8(4S) 

Hardware  Reference  Manual;  Octal  Serial  Interface^  Central  Data  Corporation  (Sun  800-0418) 

DIAGNOSTICS 

None. 

BDGS 

Input  data  overruns  are  silent^  ignored. 

This  interrupt-per-character,  non-bufl'ered  device  is  expensive  in  terms  of  system  overhead. 

This  driver  is  not  supported. 
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NAME 

pty  -  pseudo  termmal  driver 

SYNOPSIS 

pseudo-device  pty 

DESCRIPTION 

The  piy  driver  provides  support  for  a  pair  of  devices  collectively  known  as  a  pseudo^terminaL 
The  two  devices  comprising  a  pseudo-terminal  are  known  as  a  masitr  and  a  elavt.  The  slave  dev¬ 
ice  provides  an  interface  identical  to  that  described  in  ^/y(4),  but  instead  of  having  a  hardware 
interface  such  as  the  Zilog  chip  and  associated  hardware  used  by  2rs(4S)  supporting  the  terminal 
functions,  the  functions  of  the  terminal  are  implemented  by  another  process  manipulating  the 
master  side  of  the  pseudo-terminal* 

The  master  and  the  slave  sides  of  the  pseudo^terminal  are  tightly  connected.  Any  data  written  on 
the  master  device  is  given  to  the  slave  device  as  input,  as  though  it  had  been  received  from  a 
hardware  interface*  Any  data  written  on  the  slave  terminal  can  be  read  from  the  master  device 
(rather  than  being  transmitted  from  a  UART)* 

In  configuring,  if  no  optional  ^*count*’  is  given  in  the  specification,  16  pseudo  terminal  pairs  are 
configured. 

A  few  special  iocti’s  a^e  provided  on  the  control-side  devices  of  pseudo-terminals  to  provide  the 
functionality  needed  by  applications  programs  to  emulate  real  hardware  interfaces: 

TIOCSTOP 

Stops  output  to  a  terminal  (that  is,  like  typing  "S).  Takes  no  parameter. 

TIOCSTART 

Restarts  output  (stopped  by  TIOCSTOP  or  by  typing  "Q)*  Takes  no  parameter. 

There  are  also  two  independent  modes  which  can  be  used  by  applications  programs: 

TIOCPKT 

Enable/disable  packet  mode.  Packet  mode  is  enabled  by  specifying  (by  reference)  a 
nonzero  parameter  and  disabled  by  specifying  (by  reference)  a  zero  parameter.  When 
applied  to  the  master  side  of  a  pseudo  terminal,  each  subsequent  read  from  the  terminal 
will  return  data  written  on  the  slave  part  of  the  pseudo  terminal  preceded  by  a  zero  byte 
(symbolically  defined  as  TIOCPKT J>  AT  A),  or  a  single  byte  reflecting  control  status 
information*  In  the  latter  case,  the  byte  is  an  inclusive-or  of  zero  or  more  of  the  bits: 

TIOCPKT JLUSHREAD 

whenever  the  read  queue  for  the  terminal  is  flushed. 

TIOCPKT_rLUSHWRITE 

whenever  the  write  queue  for  the  terminal  is  flushed. 

TIOCPKT_STOP’ 

whenever  output  to  the  terminal  is  stopped  a  la  ^S* 

TIOCPKT.START 

whenever  output  to  the  terminal  is  restarted* 

Tl6CPKTJ)OSTOP 

whenever  tjBtopciB  and  t^etartciB  "Q. 

TIOCPKT.NOSTOP 

whenever  the  start  and  stop  characters  are  not  ^S/^Q. 

This  mode  is  used  by  rfoi?m(lC)  and  rf(?pmd(8C)  to  implement  a  remote-echoed,  locally 
"S/"Q  flow-controlled  remote  login  with  proper  back-flushing  of  output  when  interrupts 
occur;  it  can  be  used  by  other  similar  programs. 

TIOCREMOTE 
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A  mode  for  the  master  half  of  a  pseudo  terminal,  independent  of  TIOCPKT.  This  mode 
causes  input  to  the  pseudo  terminal  to  be  flow  controlled  and  not  input  edited  (regardless 
of  the  terminal  mode).  Each  write  to  the  control  terminal  produces  a  record  boundary  for 
the  process  reading  the  terminal.  In  normal  usage,  a  write  of  data  is  like  the  data  typed 
as  a  line  on  the  terminal;  a  write  of  0  bytes  is  like  typing  an  end-of-file  character. 
TIOCREMOTE  can  be  used  when  doing  remote  line  editing  in  a  window  manager,  or 
whenever  flow  controlled  input  is  required. 

/dev/pty|p-r)|0-9ai-fj  master  pseudo  terminals 
/dev/tty(p-r](0-9a-fl  slave  pseudo  terminals 

It  is  apparently  not  possible  to  send  an  EOT  by  writing  zero  bytes  in  TIOCREMOTE  mode. 
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NAME 

routing  -  system  supporting  for  local  network  packet  routing 
DESCRIPTION 

The  network  facilities  provided  general  packet  routing,  leaving  routing  table  maintenance  to 
applications  processes. 

A  simple  set  of  data  structures  comprise  a  “routing  table”  used  in  selecting  the  appropriate  net¬ 
work  interface  when  transmitting  packets.  This  table  contains  a  single  entry  for  each  route  to  a 
specidc  network  or  host.  A  user  process,  the  routing  daemon,  maintains  this  data  base  with  the 
aid  of  two  socket  specific  iocU{2)  commands,  SIOGADDRT  and  SIOCDELRT.  The  commands 
allow  the  addition  and  deletion  of  a  single  routing  table  entry,  respectively.  Routing  table  mani¬ 
pulations  may  only  be  carried  out  by  super-^user. 

A  routing  table  entry  has  the  following  form,  as  defined  in  <nc^/rou^c.&>; 

struct  rtentry  { 

ujong  rt^hash; 
struct  sockaddr  rt_dst; 
struct  sockaddr  rt^gateway; 
short  rt^flags; 
short  rOefent; 
u Jong  rt^use; 
struct  ifnet  *rtjfp; 

}; 

with  rt^fiags  from, 

#defineRTFJUP  0x1  /*  route  usable  ♦/ 

#define  RTF^GATEWAY  0x2  /*  destination  is  a  gateway  ♦/ 

#defineRTFJIOST  0x4  /*  host  entry  (net  otherwise)  */ 

Routing  table  entries  come  in  three  fiavors:  for  a  specific  host,  for  all  hosts  on  a  specific  network, 
for  any  destination  not  matched  by  entries  of  the  first  two  types  (a  wildcard  route).  When  the 
system  is  booted,  each  network  interface  autoconfigured  installs  a  routing  table  entry  when  it 
wishes  to  have  packets  sent  through  it.  Normally  the  interface  specifies  the  route  through  it  is  a 
“direct”  connection  to  the  destination  host  or  network.  If  the  route  is  direct,  the  transport  layer 
of  a  protocol  family  usually  requests  the  packet  be  sent  to  the  same  host  specified  in  the  packet. 
Otherwise,  the  interface  may  be  requested  to  address  the  packet  to  an  entity  different  from  the 
eventual  recipient  (i.e.  the  packet  is  forwarded). 

Routing  table  entries  installed  by  a  user  process  may  not  specify  the  hash,  reference  count,  use,  or 
interface  fields;  these  are  filled  in  by  the  routing  routines.  If  a  route  is  in  use  when  it  is  deleted 
{rtjrefcnt  is  non-zero),  the  resources  associated  with  it  will  not  be  reclaimed  until  further  refer¬ 
ences  to  it  are  released. 

The  routing  code  returns  EEXIST  if  requested  to  duplicate  an  existing  entry,  ESRCH  if  requested 
to  delete  a  non-existant  entry,  or  ENOBUFS  if  insufficient  resources  were  available  to  install  a 
new  route. 

User  processes  read  the  routing  tables  through  the  /dev/imem  device. 

The  rt^use  field  contains  the  number  of  packets  sent  along  the  route.  This  value  is  used  to  select 
among  multiple  routes  to  the  same  destination.  When  multiple  routes  to  the  same  destination 
exist,  the  least  used  route  is  selected. 

A  wildcard  routing  entry  is  specified  with  a  zero  destination  address  value.  Wildcard  routes  are 
used  only  when  the  system  fails  to  find  a  route  to  the  destination  host  and  network.  The  combi¬ 
nation  of  wildcard  routes  and  routing  redirects  can  provide  an  economical  mechanism  for  routing 
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traffic. 

SEE  ALSO 

route(8C),  routed(8C) 
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NAME 

sd  -  Disk  driver  for  Adaptec  ST-506  Disk  Controllers 
SYNOPSIS 

controller  scO  at  mbO  ear  0x80000  priority  2 
disk  adO  at  seO  drive  0  flags  0 
disk  sdl  at  scO  drive  1  flags  0 

DESCRIPTION 

Files  with  minor  device  numbers  0  through  7  refer  to  various  portions  of  drive  0.  The  standard 
device  names  begin  with  "sd”  followed  by  the  drive  number  and  then  a  letter  a-h  for  partitions 
0-7  respectively.  The  charsMSter  ?  stands  here  for  a  drive  number  in  the  range  0-7. 

The  block  file’s  access  the  disk  via  the  system’s  normal  buffering  mechanism  and  may  be  read  and 
written  without  regard  to  physical  disk  records.  There  is  also  a  ‘raw’  interface  which  provides  for 
direct  transmission  between  the  disk  and  the  user’s  read  or  write  buffer.  A  single  read  or  write 
call  results  in  exactly  one  I/O  operation  and  therefore  raw  I/O  is  considerably  more  effficient 
when  many  words  are  transmitted.  The  names  of  the  raw  files  conventionally  begin  with  an  extra 
‘r.’ 

In  raw  I/O  counts  should  be  a  multiple  of  512  bytes  (a  disk  sector).  Likewise  seek  calls  should 
specify  a  multiple  of  512  bytes. 

DISK  SUPPORT 

This  driver  handles  all  ST-506  drives,  by  reading  a  label  from  sector  0  of  the  drive  which 
describes  the  disk  geometry  and  partitioning. 

The  sdfa  partition  is  normally  used  for  the  root  file  system  on  a  disk,  the  sd?b  partition  as  a  pag¬ 
ing  area,  and  the  sdfc  partition  for  pack-pack  copying  (it  normally  maps  the  entire  disk).  The 
t  rest  of  the  disk  is  normally  the  sd?h  partition. 

FILES 

/dev/8d|0-7][aFhj  block  files 

/dev/r6d|0-7j(arh)  raw  files 

SEE  ALSO 

dkio(4S) 

Ad^tec  ACB  4000  and  5000  Series  Disk  Controllers  OEM  Manual 
DIAGNOSTICS 

sd%d%ct  emd  how  (msg)  blk  %d.  A  command  such  as  read  or  write  encountered  a  error  condi¬ 
tion  (how);  either  it  failed,  the  unit  was  restored,  or  an  operation  was  relr]/ed.  The  msg  is 
derived  from  the  error  number  given  by  the  controller,  indicating  a  condition  such  as  "drive  not 
ready”  or  "sector  not  found”. 

BUGS 

In  raw  I/O  read  and  wrUe{2)  truncate  file  offsets  to  512-byte  block  boundaries,  and  write  scribbles 
on  the  tail  of  incomplete  blocks.  Thus,  in  programs  that  are  likely  to  access  raw  devices,  read, 
write  and  leeek{2)  should  always  deal  in  512-byte  multiples. 
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NAME 

St  -  Driver  for  Sysgen  SC  4000  (Archive)  Tape  Controller 
SYNOPSIS 

controller  bcO  at  mbO  esr  0x80000  priority  2 
tape  BtO  at  bcO  drive  32  flags  1 

DESCRIPTION 

The  Sysgea  tape  controller  is  a  SCSI  bus  interface  to  an  Archive  streaming  tape  drive.  It  pro¬ 
vides  a  standard  tape  interface  to  the  device,  see  miio{A),  with  some  deficiencies  listed  under 
BUGS  below. 

FILES 

/dev/rstO 

/dev/nrstO  non-rewinding 

SEE  ALSO 

mtio(4),  tm(4S) 

Sysgen  SC4000  Intelligent  Tape  Controller  Product  Specification 

Archive  Intelligent  Tape  Drive  Theory  of  Operation,  Archive  Corporation  (Sun  8000-1058-01) 
Archive  Product  Manual  (Sidewinder  1/4**  Streaming  Cartridge  Tape  Drive)  (Sun  800-0628-01) 

DIAGNOSTICS 

Bt%dt  tape  not  online. 

st%di  no  cartridge  in  drive. 

Bt%dt  cartridge  Is  write  protected. 

BUGS 

The  tape  cannot  reverse  direction  so  BSP  and  BSR  are  not  available. 

Disk  I/O  over  the  SCSI  bus  will  be  mostly  blocked  out  when  the  tape  is  in  use.  This  is  because 
the  controller  does  not  free  the  bus  while  the  tape  is  in  motion  (even  during  rewind). 

When  using  the  raw  device,  the  number  of  bytes  in  any  given  transfer  must  be  a  multiple  of  512 
bytes.  If  it  is  not,  the  device  driver  returns  an  error. 
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NAME 

tcp  -  Internet  Transmission  Control  Protocol 


SYNOPSIS 

None;  comes  automatically  with  inel(4F). 


DESCRIPTION 

TCP  is  a  connection-oriented,  end-to-end  reliable  protocol  designed  to  fit  into  a  layered  hierarch 
of  protocols  which  support  multi-network  applications.  TCP  provides  for  reliable  inter-process 
communication  between  pairs  of  processes  in  host  computers  attached  to  distinct  but  intercon¬ 
nected  computer  communication  networks.  Veiy  few  assumptions  are  made  as  to  the  reliability 
of  the  communication  protocols  below  TCP  layer.  TCP  assumes  it  can  obtain  a  simple,  poten¬ 
tially  unreliable  datagram  service  from  the  lower  level  protocok.  In  principle,  TCP  should  be 
able  to  operate  above  a  wide  spectrum  of  communication  systems  ranging  from  hard-wired  con¬ 
nections  to  packet^switched  or  circuit  switched  networks. 

TCP  fits  into  a  layered  protocol  architecture  just  above  the  basic  Internet  Protocol  (IP)  described 
in  ij>(4P)  which  provides  a  way  for  TCP  to  send  and  receive  variable-length  segments  of  informa¬ 
tion  enclosed  in  Internet  datagram  * ‘envelopes.’’  The  Internet  datagram  provides  a  means  for 
addressing  source  and  destination  TCPs  in  different  networks,  deals  with  any  fragmentation  or 
reassembly  of  the  TCP  segments  required  to  achieve  transport  and  delivery  through  multiple 
netwokrs  and  interconnecting  gateways,  and  has  the  ability  to  carry  information  on  the  pre¬ 
cedence,  security  classification  and  compartmentalization  of  the  TCP  segments  (although  this  is 
not  currently  implemented  under  UNIX.) 

An  application  process  interfaces  to  TCP  through  the  socket{2)  abstraction  and  the  related  calles 
bind{2),  H8ten{2),  accept{2)^  conneet{2),  eend{2)  and  recv{2).  The  primary  purpose  of  TCP  is  to 
provide  a  reliable  bidirectional  virtual  circuit  service  between  pairs  of  processes.  In  general,  the 
TCP’s  decide  when  to  block  and  forward  data  at  their  own  convenience.  In  the  UNIX  implemen¬ 
tation,  it  is  assumed  that  any  buffering  of  data  is  done  at  the  user  level,  the  TCP’s  transmit 
available  data  as  soon  as  possible  to  their  remote  peer.  They  do  this  and  always  set  the  PUSH  bit 
indicating  that  the  transferred  data  should  be  made  available  to  the  user  process  at  the  remote 
end  as  soon  as  practicable. 


To  provide  reliable  data  TCP  must  recover  from  data  that  is  damaged,  lost,  duplicated,  or 
delivered  out  of  order  by  the  underlying  internet  communications  system.  This  is  achieved  by 
assigning  a  sequence  number  to  each  byte  of  data  transmitted  and  requiring  a  positive  ack¬ 
nowledgement  from  the  receiving  TCP.  If  the  ACK  is  not  received  within  an  (adaptively  deter¬ 
mined)  timeout  interval  the  data  is  retransmitted.  At  the  receiver,  the  sequence  numbers  are 
used  to  correctly  order  segments  that  may  be  received  out  of  order  and  to  eliminate  duplicates. 
Damage  is  handled  by  adding  a  checksum  to  each  segment  transmitted,  checking  it  at  the 
receiver,  and  discarding  damaged  segments.  As  long  as  the  TCP’s  continue  to  function  properly 
and  the  internet  system  does  nqt  become  completely  partitioned,  no  tranmksion  errors  will  affect 
the  correct  delivery  of  data,  as  TbP  recovers  from  communications  errors. 


TCP  provides  flow  control  over  the  transmitted  data.  The  receiving  TCP  is  allowed  to  specify 
the  amount  of  data  which  may  be  sent  by  the  sender,  by  returning  a  window  with  every  ack¬ 
nowledgement  indicating  a  range  of  acceptable  sequence  numbers  beyond  the  last  segment  suc¬ 
cessfully  received.  The  window  indicates  an  allowed  number  of  bytes  that  the  sender  may 
transmit  before  receiving  further  permission. 


TCP  extends  the  standard  32-bit  Internet  host  addresses  with  a  16-bit  port  number  space;  the 
combined  addresses  are  available  at  the  UNIX  process  level  in  the  standard  sockaddrjin  format 
described  in  ine^(4P). 


Sockets  utilizing  the  tcp  protocol  are  either  “active”  or  “passive”.  Active  sockets  initiate  connec¬ 
tions  to  passive  sockets.  By  default  TCP  sockets  are  created  active;  to  create  a  passive  socket  the 
ti8i€n{2)  system  call  must  be  used  after  binding  the  socket  to  an  address  with  the  6md(2)  system 
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call.  Only  passive  sockets  may  use  the  accept{2)  call  to  accept  incoming  connections.  Only 
active  sockets  may  use  the  connect{2)  call  to  initiate  connections. 

Passive  sockets  may  ^^underspecify*’  their  location  to  match  incoming  connection  requests  from 
multiple  networks.  This  technique^  termed  ^‘wildcard  addressing’^  allows  a  single  server  to  pro¬ 
vide  service  to  clients  on  multiple  networks.  To  create  a  socket  which  listens  on  all  networks,  the 
Internet  address  INADDR^NY  must  be  bound.  The  TCP  port  may  still  be  specified  at  this 
time;  if  the  port  is  not  specified  the  system  will  assign  one.  Once  a  connection  has  been  esta- 
blished  the  socket’s  address  is  fixed  by  the  peer  entity’s  location.  The  address  assigned  the 
socket  is  the  address  associated  with  the  network  interface  through  which  packets  are  being 
transmitted  and  received.  Normally  this  address  corresponds  to  the  peer  entity’s  network.  See 
me^(4F)  for  a  complete  description  of  addressing  in  the  Internet  family. 

A  TCP  connection  is  created  at  the  server  end  by  doing  a  eocket{2),  a  bind{2)  to  establish  the 
address  of  the  socket,  a  iisten{2)  to  cause  connection  queueing,  and  then  an  acctpi(2)  which 
returns  the  descriptor  for  the  socket.  A  client  connects  to  the  server  by  doing  a  8ocket(2)  and 
then  a  conntct{2).  Data  may  then  be  sent  from  server  to  client  and  back  using  read(2)  and 
write{2), 

TCP  implements  a  very  weak  out-of-band  mechanism,  which  may  be  invoked  using  the  out-of- 
band  provisions  of  scnd(2).  This  mechanism  allows  setting  an  urgent  pointer  in  the  data  stream; 
it  is  reflected  to  the  TCP  user  by  making  the  byte  after  the  urgent  pointer  available  as  out-of- 
band  data  and  providing  a  SIOCATMARK  ioctl  which  returns  an  integer  indicating  whether  the 
stream  is  at  the  urgent  mark.  The  system  never  returns  data  across  the  urgent  mark  in  a  single 
read.  Thus  when  a  SIGURG  signal  is  received  indicating  the  presence  of  out-of-band  data  and 
the  out-of-band  data  indicates  that  the  data  to  the  mark  should  be  flushed  (as  in  remote  terminal 
processing)  it  suffices  to  loop  checking  whether  you  are  at  the  out-of-band  mark,  and  reading  data 
while  you  are  not  at  the  mark. 

SEE  ALSO 

inet(4F),  ip(4P) 

BUGS 

It  should  be  possible  to  send  and  receive  TCP  options. 

The  system  always  tries  to  negotiates  the  maximum  TCP  segment  size  to  be  1024  bytes.  This 
can  result  in  poor  performance  if  an  intervening  network  performs  excessive  fragmentation. 

SIOCSHIWAT  and  SIOCGHIWAT  ioctl’s  to  set  and  get  the  high  water  mark  for  the  socket 
queue,  and  so  that  it  can  be  changed  from  2048  bytes  to  be  larger  or  smaller,  have  been  defined 
(in  <sys/ioctl.h>)  but  not  implemented. 
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NAME 

tm  -  tapemaster  1/2  inch  tape  drive 
SYNOPSIS 

controller  tmO  at  mbO  csr  OxaO  priority  3 
tape  mtO  at  tmO  drive  0  flags  1 

DESCRIPTION 

The  Tapemaster  tape  controller  controls  Pertec-interface  1/2’*  tape  drives  such  as  the  CDC  Key¬ 
stone,  providing  a  standard  tape  interface  to  the  device,  see  m^io(4). 

SEE  ALSO 

mt(l),  tar(l),  ar(4S) 

CPC  Tapemaster  Product  Specification  (Sun  800-0620-01) 

CPC  Tapemaster  Application  Note  (Sun  800-0622-01) 

CDC  Streaming  Tape  Unit  9218X  Reference  Manual  (Sun  800-0628-01) 

DIAGNOSTICS 

tm%ds  no  responie  from  ctlr. 
tm%di  error  %d  during  conflg. 
mi%di  not  online. 
mt%dt  no  write  ring. 

tmgos  gate  wasnH  open.  Controller  lost  synch, 
tmintri  can^t  clear  interrupts. 
tm%di  stray  Interrupte. 
mt%ds  hard  error  bn«%d  ers=%x. 
mt%ds  lost  interrupt. 

BUGS 

The  Tapemaster  controller  does  not  provide  for  byte-swapping  and  the  resultant  system  overhead 
prevents  streaming  transports  from  streaming. 

If  a  non-data  error  is  encountered  on  non-raw  tape,  it  refuses  to  do  anything  more  until  closed. 

The  ^stem  should  remember  which  controlling  terminal  has  the  tape  drive  open  and  write  error 
messages  to  that  terminal  rather  than  on  the  console. 
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NAME 

tty  -  general  terminal  interface 
SYNOPSIS 

None;  included  by  default. 

DESCRIPTION 

This  section  describes  both  a  particular  special  file  /dev /tty  and  the  terminal  drivers  used  for 
conversational  computing  by  serial  interfaces  such  as  uel(4S),  ^(4S),  as  well  as  cons(4S)  and 
ply(4). 

Line  discipUnese 

The  system  provides  different  lint  dhciplintB  for  controlling  communications  lines.  In  this  version 
of  the  system  there  are  three  disciplines  available: 

old  The  old  (standard)  terminal  driver.  This  is  used  when  using  the  standard  shell  sA(l)  and 
for  compatibility  with  version  7  UNIX  systems. 

new  A  newer  terminal  driver,  with  features  for  job  control;  this  must  be  used  when  using 
csh(l). 

net  A  line  discipline  used  for  networking  and  loading  data  into  the  system  over  communic^ 
tions  lines.  It  allows  high  speed  input  at  very  low  overhead,  and  is  described  in  M:(4). 

Line  discipline  switching  is  accomplished  with  the  TIOCSETD  ioctl: 

Int  Idlsc  »  LDlSCf  loctl(f,  TIOCSBTDp  &ldl8c)| 

where  LDISC  is  OTTYDISC  for  the  standard  tty  driver,  NTTYDISC  for  the  new  driver  and 
NETLDISC  for  the  networking  discipline.  The  standard  (currently  old)  tty  driver  is  discipline  0 
by  convention.  The  current  line  discipline  can  be  obtained  with  the  TIOCGETD  ioctl.  Pending 
input  is  discarded  when  the  line  discipline  is  changed. 

All  of  the  low-speed  asynchronous  communications  ports  can  use  any  of  the  available  line  discip¬ 
lines,  no  matter  what  hardware  is  involved.  The  remainder  of  this  section  discusses  the  “old”  and 
“new”  disciplines" 

The  control  terminal. 

When  a  terminal  file  is  opened,  it  causes  the  process  to  wait  until  a  connection  is  established.  In 
practice,  user  programs  seldom  open  these  files;  they  are  opened  by  in»^(8)  and  become  a  user’s 
standard  input  and  output  file. 

If  a  process  which  has  no  control  terminal  opens  a  terminal  file,  then  that  terminal  file  becomes 
the  control  terminal  for  that  process.  The  control  terminal  is  thereafter  inherited  by  a  child  pro¬ 
cess,  during  a  fork{2),  even  if  the  control  terminal  is  closed. 

The  file  /dev/tty  is,  in  each  process,  a  synonym  for  a  control  Vermins/  associated  with  that  pro¬ 
cess.  It  is  useful  for  programs  that  wish  to  be  sure  of  writing  messages  on  the  terminal  no  matter 
how  output  has  been  redirected.  It  can  also  be  used  for  programs  that  demand  a  file  name  for 
output,  when  typed  output  is  desired  and  it  is  tiresome  to  find  out  which  terminal  is  currently  in 
use. 

A  process  can  remove  the  association  it  has  with  its  controlling  terminal  by  opening  the  file 
/dev/tty  and  issuing  a 

loctl(f,  TIOCNOTTY,  0)| 

This  is  often  desirable  in  server  processes. 

Process  groups. 

Command  processors  such  as  csA(l)  can  arbitrate  the  terminal  between  different  jobs  by  placing 
related  jobs  in  a  single  process  group  and  associating  this  process  group  with  the  terminal.  A 
terminal’s  associated  process  group  may  be  set  using  the  TIOCSPGRP  ioctl{2): 
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locti(aides,  TIOCSPGRP,  &pgrp) 

or  examined  using  TIOCGPGRP,  returning  the  current  process  group  in  pgrp.  The  new  terminal 
driver  aids  in  this  arbitration  by  restricting  access  to  the  terminal  by  processes  which  are  not  in 
the  current  process  group;  see  Job  access  control  below. 

Modes. 

The  terminal  drivers  have  three  major  modes,  characterized  by  the  amount  of  processing  on  the 
input  and  output  characters: 

cooked  The  normal  mode.  In  this  mode  lines  of  input  are  collected  and  input  editing  is  done. 

The  edited  line  is  made  available  when  it  is  completed  by  a  newline  or  when  the 
t^brkc  character,  normally  an  EOT  (control-D,  hereafter  "D),  is  entered.  A  carriage 
return  is  usually  made  synonymous  with  newline  in  this  mode,  and  replaced  with  a 
newline  whenever  it  is  typed.  All  driver  functions  (input  editing,  interrupt  generation, 
output  processing  such  as  delay  generation  and  tab  expansion,  etc.)  are  available  in 
this  mode. 

CBREAK  This  mode  eliminates  the  character,  word,  and  line  editing  input  facilities,  making  the 
input  character  available  to  the  user  program  as  it  is  typed.  Flow  control,  literal-next 
and  interrupt  processing  are  still  done  in  this  mode.  Output  processing  is  done. 

RAW  This  mode  eliminates  all  input  processing  and  makes  all  input  characters  available  as 
they  are  typed;  no  output  processing  is  done  either. 

The  style  of  input  processing  can  also  be  very  different  when  the  terminal  is  put  in  non-blocking 
i/o  mode;  see  the  FNDELAY  flag  as  described  in  /cn^2).  In  this  case  a  rcad{2)  from  the  control 
terminal  will  never  block,  but  rather  return  an  error  indication  (EWOULDBLOCK)  if  there  is  no 
input  available. 

A  process  may  also  request  a  SIGIO  signal  be  sent  it  whenever  input  is  present.  To  enable  this 
mode  the  FASYNC  flag  should  be  set  using  fcntl{2). 

Input  editing. 

A  UNIX  terminal  ordinarily  operates  in  full-duplex  mode.  Characters  may  be  typed  at  any  time, 
even  while  output  is  occurring,  and  are  only  lost  when  the  system’s  character  input  buffers 
become  completely  choked,  which  is  rare,  or  when  the  user  has  accumulated  the  maximum 
allowed  number  of  input  characters  that  have  not  yet  been  read  by  some  program.  Currently  this 
limit  is  256  characters.  In  the  old  terminal  driver  all  the  saved  characters  are  thrown  away  when 
the  limit  is  reached,  without  notice;  the  new  driver  simply  refuses  to  accept  any  further  input, 
and  rings  the  terminal  bell. 

Input  characters  are  normally  accepted  in  either  even  or  odd  parity  with  the  parity  bit  being 
stripped  off  before  the  character  is  given  to  the  program.  By  clearing  either  the  EVEN  or  ODD 
bit  in  the  flags  word  it  is  possible  to  have  input  characters  with  that  parity  discarded  (see  the 
Summitry  below.) 

In  all  of  the  line  disciplines,  it  is  possible  to  simulate  terminal  input  using  the  TIOCSTl  ioct), 
which  takes,  as  its  third  argument,  the  address  of  a  character.  The  ^stem  pretends  that  this 
character  was  typed  on  the  argument  terminal,  which  must  be  the  control  terminal  except  for  the 
super-user  (this  call  is  not  in  standard  version  7  UNDC). 

Input  characters  are  normally  echoed  by  putting  them  in  an  output  queue  as  they  arrive.  This 
may  be  disabled  by  clearing  the  ECHO  bit  in  the  flags  word  using  the  s^f|/(3C)  call  or  the 
TIOCSETN  or  TIOCSETP  ioctls  (see  the  Summary  below). 

In  cooked  mode,  terminal  input  is  processed  in  units  of  lines.  A  program  attempting  to  read  will 
normally  be  suspended  until  an  entire  line  has  been  received  (but  see  the  description  of  SIGTTIN 
in  Modes  above  and  FIONREAD  in  Summary  below.)  No  matter  how  many  characters  are 
requested  in  the  read  call,  at  most  one  line  will  be  returned.  It  is  not,  however,  necessary  to  read 
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a  whole  line  at  once;  any  number  of  characters  may  be  requested  in  a  read,  even  one,  without  los¬ 
ing  information. 

During  input,  line  editing  is  normally  done,  with  the  DELETE  character  logically  erasing  the  last 
character  typed  and  a  ''U  (control-U)  logically  erasing  the  entire  current  input  line.  These  charac¬ 
ters  never  erase  beyond  the  beginning  of  the  current  input  line  or  an  'D.  These  characters  may 
be  entered  literally  by  preceding  them  with  in  the  old  teletype  driver  both  the  ‘\’  and  the 
character  entered  literally  will  appear  on  the  screen;  in  the  new  driver  the  ‘\  ’  will  normally  disap¬ 
pear. 

The  drivers  normally  treat  either  a  carriage  return  or  a  newline  character  as  terminating  an  input 
line,  replacing  the  return  with  a  newline  and  echoing  a  return  and  a  line  feed.  If  the  CRMOD  bit 
is  cleared  in  the  local  mode  word  then  the  processing  for  carriage  return  is  disabled,  and  it  is  sim¬ 
ply  echoed  as  a  return,  and  does  not  terminate  cooked  mode  input. 

In  the  new  driver  there  is  a  literal-next  character  'V  which  can  be  typed  in  both  cooked  and 
CBREAK  mode  preceding  any  character  to  prevent  its  special  meaning.  This  is  to  be  preferred 
to  the  use  of  ‘\  ’  escaping  erase  and  kill  characters,  but  ‘\  ’  is  (at  least  temporarily)  retained  with 
its  old  function  in  the  new  driver  for  historical  reasons. 

The  new  terminal  driver  also  provides  two  other  editing  characters  in  normal  mode.  The  word- 
erase  character,  normally  *W,  erases  the  preceding  word,  but  not  any  spaces  before  it.  For  the 
purposes  of  *W,  a  word  is  defined  as  a  sequence  of  non-blank  characters,  with  tabs  counted  as 
blanks.  Finally,  the  reprint  character,  normally  *R,  retypes  the  pending  input  beginning  on  a 
new  line.  Retyping  occurs  automatically  in  cooked  mode  if  characters  which  would  normally  be 
erased  from  the  screen  are  fouled  by  program  output. 

Input  echoing  and  redisplay 

In  the  old  terminal  driver,  nothing  special  occurs  when  an  erase  character  is  typed;  the  erase  char¬ 
acter  is  simply  echoed.  When  a  kill  character  is  typed  it  is  echoed  followed  by  a  new-line  (even  if 
the  character  is  not  killing  the  line,  because  it  was  preceded  by  a  ‘\’!,) 

The  new  terminal  driver  has  several  modes  for  handling  the  echoing  of  terminal  input,  controlled 
by  bits  in  a  local  mode  word. 

Hardcopy  terminals.  When  a  hardcopy  terminal  is  in  use,  the  LPRTERA  bit  is  normally  set  in  the 
local  mode  word.  Characters  which  are  logically  erased  are  then  printed  out  backwards  preceded 
by  ‘\  ’  and  followed  by  in  this  mode. 

Crt  terminals.  When  a  ert  terminal  is  in  use,  the  LCRTBS  bit  is  normally  set  in  the  local  mode 
word.  The  terminal  driver  then  echoes  the  proper  number  of  backspace  characters  when  input  is 
erased  to  reposition  the  cursor.  If  the  input  has  become  fouled  due  to  interspersed  a^nchronous 
output,  the  input  is  automatically  retyped. 

Erasing  characters  from  a  crt.  When  a  crt  terminal  is  in  use,  the  LCRTERA  bit  may  be  set  to 
cause  input  to  be  erased  from  the  screen  with  a  “backspace-space-backspace”  sequence  when 
character  or  word  deleting  sequences  are  used.  A  LCRTKIL  bit  may  be  set  as  well,  causing  the 
input  to  be  erased  in  this  manner  on  line  kill  sequences  as  well. 

Echoing  of  control  characters.  If  the  LCTLECH  bit  is  set  in  the  local  state  word,  then  non¬ 
printing  (control)  characters  are  normally  echoed  as  ‘X  (for  some  X)  rather  than  being  echoed 
unmodified;  delete  is  echoed  as 

The  normal  modes  for  using  the  new  terminal  driver  on  crt  terminals  are  speed  dependent.  At 
speeds  less  than  1200  baud,  the  LCRTERA  and  LCRTKILL  processing  is  painfully  slow,  so 
s<ly(l)  normally  just  sets  LCRTBS  and  LCTLECH;  at  speeds  of  1200  baud  or  greater  all  of  these 
bits  are  normally  set.  The  s»i/(l)  command  summarizes  these  option  settings  and  the  use  of  the 
new  terminal  driver  as  “newert.” 
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Output  proceulng. 

When  one  or  more  characters  are  written^  they  are  actually  transmitted  to  the  terminal  as  soon  as 
previously-written  characters  have  finished  typing.  (As  noted  above,  input  characters  are  nor¬ 
mally  echoed  by  putting  them  in  the  output  queue  as  they  arrive,)  When  a  process  produces  char¬ 
acters  more  rapidly  than  they  can  be  typed,  it  will  be  suspended  when  its  output  queue  exceeds 
some  limit.  When  the  queue  has  drained  down  to  some  threshold  the  program  is  resumed.  Even 
parity  is  normally  generated  on  output.  The  EOT  character  is  not  transmitted  in  cooked  mode  to 
prevent  terminals  that  respond  to  it  from  hanging  up;  programs  using  raw  or  cbreak  mode  should 
be  careful. 

The  terminal  drivers  provide  necessary  processing  for  cooked  and  CBREAK  mode  output  includ¬ 
ing  delay  generation  for  certain  special  characters  and  parity  generation.  Delays  are  available 
after  backspaces  form  feeds  "L,  carriage  returns  "M,  tabs  T  and  newlines  "  J.  The  driver  will 
also  optionally  expand  tabs  into  spaces,  where  the  tab  stops  are  assumed  to  be  set  every  eight 
columns.  These  functions  are  controlled  by  bits  in  the  tty  flags  word;  see  Summary  below. 

The  terminal  drivers  provide  for  mapping  between  upper  and  lower  case  on  terminals  lacking 
lower  case,  and  for  other  special  processing  on  deficient  terminals. 

Finally,  in  the  new  terminal  driver,  there  is  an  output  flush  character,  normally  "O,  which  sets 
the  LFLUSHO  bit  in  the  local  mode  word,  causing  subsequent  output  to  be  flushed  until  it  is 
cleared  by  a  program  or  more  input  is  typed.  This  character  has  effect  in  both  cooked  and 
CBREAK  modes  and  causes  pending  input  to  be  retyped  if  there  is  any  pending  input.  An  ioctl 
to  flush  the  characters  in  the  input  and  output  queues,  TIOCFLUSH,  is  also  available. 

Upper  cue  termlnahi  and  Haseltinee 

If  the  LCASE  bit  is  set  in  the  tty  flags,  then  aH  upper-case  letters  are  mapped  into  the 
corresponding  lower-case  letter.  The  upper-case  letter  may  be  generated  by  preceding  it  by  *\’.  If 
the  new  terminal  driver  is  being  used,  then  upper  case  letters  are  preceded  by  a  *  when  output. 
In  addition,  the  following  escape  sequences  can  be  generated  on  output  and  accepted  on  input: 

for  '  I  ~  } 

ase  \'  \!  \‘  \(  \) 

To  deal  with  Hazeltine  terminals,  which  do  not  understand  that  "  has  been  made  into  an  ASCII 
character,  the  LTILDE  bit  may  be  set  in  the  local  mode  word  when  using  the  new  terminal 
driver;  in  this  case  the  character  ~  will  be  replaced  with  the  character  '  on  output. 

Plow  controL 

There  are  two  characters  (the  stop  character,  normally  "S,  and  the  start  character,  normally  "Q) 
which  cause  output  to  be  suspended  and  resumed  respectively.  Extra  stop  characters  typed  when 
output  is  already  stopped  have  no  effect,  unless  the  start  and  stop  characters  are  m^de  the  same, 
in  which  case  output  resumes. 

A  bit  in  the  flags  word  may  be  set  to  put  the  terminal  into  TANDEM  mode.  In  this  mode  the 
system  produces  a  stop  character  (default  ^S)  when  the  input  queue  is  in  danger  of  overflowing, 
and  a  start  character  (default  "Q)  when  the  input  has  drained  sufficiently.  This  mode  is  useful 
when  the  terminal  is  actually  another  machine  that  obeys  the  conventions. 

Line  control  and  breakn« 

There  are  several  ioctl  cnlls  available  to  control  the  state  of  the  terminal  line.  The  TIOCSBRK 
ioctl  will  set  the  break  bit  in  the  hardware  interface  causing  a  break  condition  to  exist;  this  can 
be  cleared  (usually  after  a  delay  with  s/cep(S))  by  TIOCCBRK.  Break  conditions  in  the  input  are 
reflected  as  a  null  character  in  RAW  mode  or  as  the  interrupt  character  in  cooked  or  CBREAK 
mode.  The  TIOOCDTR  ioctl  will  clear  the  data  terminal  ready  condition;  it  can  be  set  again  by 
TIOeSDTR. 
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When  the  carrier  signal  from  the  dataset  drops  (usually  because  the  user  has  hung  up  his  termi¬ 
nal)  a  SIGHUP  hangup  signal  is  sent  to  the  processes  in  the  distinguished  process  group  of  the  ter¬ 
minal;  this  usually  causes  them  to  terminate  (the  SIGHUP  can  be  suppressed  by  setting  the 
L NOHANG  bit  in  the  local  state  word  of  the  driver.)  Access  to  the  terminal  by  other  processes  is 
then  normally  revoked^  so  any  further  reads  will  fail,  and  programs  that  read  a  terminal  and  test 
for  end-of-flle  on  their  input  will  terminate  appropriately. 

When  using  an  ACU  it  is  possible  to  ask  that  the  phone  line  be  hung  up  on  the  last  close  with  the 
TIOCHPCL  ioctl;  this  is  normally  done  on  the  outgoing  line. 

Interrupt  characters. 

There  are  several  characters  that  generate  interrupts  in  cooked  and  CBREAK  mode;  all  are  sent 
to  the  processes  in  the  control  group  of  the  terminal,  as  if  a  TIOCGPGRP  ioctl  were  done  to  get 
the  process  group  and  then  a  killpg{2)  system  call  were  done,  except  that  these  characters  also 
flush  pending  input  and  output  when  typed  at  a  terminal  (&'  Ha  TIOCFLUSH).  The  characters 
shown  here  are  the  defaults;  the  field  names  in  the  structures  (given  below)  are  also  shown.  The 
characters  may  be  changed. 

"C  tjhitrc  (ETX)  generates  a  SIGINT  signal.  This  is  the  normal  way  to  stop  a  process 
which  is  no  longer  interesting,  or  to  regain  control  in  an  interactive  program. 

t_qultc  (FS)  generates  a  SIGQUIT  signal.  This  is  used  to  cause  a  program  to  terminate 
and  produce  a  core  image,  if  possible,  in  the  flle  core  in  the  current  directory. 

t_su8pc  (EM)  generates  a  SIGTSTP  signal,  which  is  used  to  suspend  the  current  process 
group. 

t_d8U8pc  (SUB)  generates  a  SIGTSTP  signal  as  does,  but  the  signal  is  sent  when  a 
program  attempts  to  read  the  *Y,  rather  than  when  it  is  typed. 

Job  access  control. 

When  using  the  new  terminal  driver,  if  a  process  which  is  not  in  the  distinguished  process  group 
of  its  control  terminal  attempts  to  read  from  that  terminal  its  process  group  is  sent  a  SIGTTIN 
signal.  This  signal  normally  causes  the  members  of  that  process  group  to  stop.  If,  however,  the 
process  is  ignoring  SIGTTIN,  has  SIGTTIN  blocked,  is  an  orphan  process,  or  is  in  the  middle  of 
process  creation  using  vfork{2)),  it  is  instead  returned  an  end-of-file.  (An  orphan  process  is  a  pro¬ 
cess  whose  parent  has  exited  and  has  been  inherited  by  the  mtl(8)  process.)  Under  older  UNIX 
systems  these  processes  would  typically  have  had  their  input  files  reset  to  /dev/nuU,  so  this  is  a 
compatible  change. 

When  using  the  new  terminal  driver  with  the  LTOSTOP  bit  set  in  the  local  modes,  a  process  is 
prohibited  from  writing  on  its  control  terminal  if  it  is  not  in  the  distinguished  process  group  for 
that  terminal.  Processes  which  are  holding  or  ignoring  SIGTTOU  signals,  which  are  orphans,  or 
which  are  in  the  middle  of  a  vfork{2)  are  excepted  and  allowed  to  produce  output. 

Summary  of  modes« 

Unfortunately,  due  to  the  evolution  of  the  terminal  driver,  there  are  4  different  structures  which 
contain  various  portions  of  the  driver  data.  The  first  of  these  (sgttyb)  contains  that  part  of  the 
information  largely  common  between  version  6  and  version  7  UNIX  systems.  The  second  contains 
additional  control  characters  added  in  version  7.  The  third  is  a  word  of  local  state  peculiar  to  the 
new  terminal  driver,  and  the  fourth  is  another  structure  of  special  characters  added  for  the  new 
driver.  In  the  future  a  single  structure  may  be  made  available  to  programs  which  need  to  access 
all  this  information;  most  programs  need  not  concern  themselves  with  all  this  state. 

Basic  modes:  settv. 

The  basic  iocth  use  the  structure  defined  in  <sgUy.h>: 
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struct  sgttyb  { 

char  sg  Ispcedi 
char  sg_08peedt 
char  Bg_erase{ 
char  sg_klll} 
short  sg_flags| 

}» 

The  9gji$peed  and  sg^oepeed  fields  describe  the  input  and  output  speeds  of  the  device  according  to 
the  fotiowing  table,  which  corresponds  to  the  DEC  DH-11  interface.  If  other  hardware  is  used, 
impossible  speed  changes  are  ignored*  Symbolic  values  in  the  table  are  as  defined  in  K.SQtty,h^ . 


BO 

0 

(hang  up  dataphone) 

B50 

1 

50  baud 

B75 

2 

75  baud 

BllO 

3 

110  baud 

B134 

4 

134.5  baud 

B150 

5 

150  baud 

B200 

6 

200  baud 

B300 

7 

300  baud 

B600 

8 

600  baud 

B1200 

9 

1200  baud 

B1800 

10 

1800  baud 

B2400 

11 

2400  baud 

B4800 

12 

4800  baud 

B9600 

13 

9600  baud 

EXTA 

14 

External  A 

EXTB 

15 

External  B 

In  the  current  configuration,  only  110,  150,  300  and  1200  baud  are  really  supported  on  dial-up 
lines.  Code  conversion  and  line  control  required  for  IBM  2741*8  (134.5  baud)  must  be  imple¬ 
mented  by  the  user’s  program.  The  half-duplex  line  discipline  required  for  the  202  dataset  (1200 
baud)  is  not  supplied;  full-duplex  212  datasets  work  fine. 

The  sg^erase  and  egjnll  fields  of  the  argument  structure  specify  the  erase  and  kill  characters 
respectively.  (Defaults  are  DELETE  and  *U.) 

The  sg^flage  field  of  the  argument  structure  contains  several  bits  that  determine  the  system’s 
treatment  of  the  terminal: 


ALLDELAY 

BSDELAY 

BSO 

BSl 

VTDELAY 

FFO 

FFl 

CRDELAY 

CRO 

CRl 

CR2 

CR3 

TBDELAY 

TABO 

TABl 

TAB2 

XTABS 


0177400  Delay  algorithm  selection 

0100000  Select  backspace  delays  (not  implemented): 

0 

0100000 

0040000  Select  form-feed  and  vertical-tab  delays: 

0 

0100000 

0030000  Select  carriage-return  delays: 

0 

0010000 

0020000 

0030000 

0006000  Select  tab  delays: 

0 

0001000 

0004000 

0006000 
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NLDELAY 

NLO 

NLl 

NL2 

NL3 

EVENP 

ODDP 

RAW 

CRMOD 

ECHO 

LCASE 

CBREAK 

TANDEM 


0001400  Select  new-line  delays: 

0 

0000400 

0001000 

0001400 

0000200  Even  parity  allowed  on  input  (most  terminals) 
0000100  Odd  parity  allowed  on  input 

0000040  Raw  mode:  wake  up  on  sJl  characters,  S*bit  interface 
0000020  Map  CR  into  LF;  echo  LF  or  CR  as  CR-LF 
0000010  Echo  (full  duplex) 

0000004  Map  upper  case  to  lower  on  input 
0000002  Return  each  character  as  soon  as  typed 
0000001  Automatic  flow  control 


The  delay  bits  specify  how  long  transmission  stops  to  allow  for  mechanical  or  other  movement 
when  certain  characters  are  sent  to  the  terminal.  In  all  cases  a  value  of  0  indicates  no  delay. 


Backspace  delays  are  currently  ignored  but  might  be  used  for  Terminet  SCO’s. 

If  a  form-feed/vertical  tab  delay  is  specified,  it  lasts  for  about  2  seconds. 

Carriage-return  delay  type  1  lasts  about  .08  seconds  and  is  suitable  for  the  Terminet  300.  Delay 
type  2  lasts  about  .16  seconds  and  is  suitable  for  the  VT05  and  the  TI  700.  Delay  type  3  is  suit¬ 
able  for  the  concept-100  and  pads  lines  to  be  at  least  9  characters  at  9600  baud. 

New-line  delay  type  1  is  dependent  on  the  current  column  and  is  tuned  for  Teletype  model  37*8. 
Type  2  is  useful  for  the  VT05  and  is  about  .10  seconds.  Type  3  is  unimptemented  and  is  0. 

Tab  delay  type  1  is  dependent  on  the  amount  of  movement  and  is  tuned  to  the  Teletype  model 
37.  Type  3,  called  XTABS,  is  not  a  delay  at  all  but  causes  tabs  to  be  replaced  by  the  appropriate 
number  of  spaces  on  output. 

Input  characters  with  the  wrong  parity,  as  determined  by  bits  200  and  100,  are  ignored  in  cooked 
and  CBREAK  mode. 


RAW  disables  all  processing  save  output  flushing  with  LFLUSHO;  full  8  bits  of  input  are  given  as 
soon  as  it  is  available;  all  8  bits  are  passed  on  output.  A  break  condition  in  the  input  is  reported 
as  a  null  character.  If  the  input  queue  overflows  in  raw  mode  it  is  discarded;  this  applies  to  both 
new  and  old  drivers. 

CRMOD  causes  input  carriage  returns  to  be  turned  into  new-lines;  input  of  either  CR  or  LF 
causes  LF-CR  both  to  be  echoed  (for  terminals  with  a  new-line  function). 

CBREIAK  is  a  sort  of  half-cooked  (rare?)  mode.  Programs  can  read  each  character  as  soon  as 
typed,  instead  of  waiting  for  a  full  line;  all  processing  is  done  except  the  input  editing:  character 
and  word  erase  and  line  kill,  input  reprint,  and  the  special  treatment  of  \  or  EOT  are  disabled. 

TANDEM  mode  causes  the  system  to  produce  a  stop  character  (default  "S)  whenever  the  input 
queue  is  in  danger  of  overflowing,  and  a  start  character  (default  "Q)  when  the  input  queue  has 
drained  sufliciently.  It  is  useful  for  flow  control  when  the  *terminar  is  really  another  computer 
which  understands  the  conventions. 


Basic  ioctls 

In  additidn  to  the  TIOCSETD  and  TIOCGETD  disciplines  discussed  in  Line  disciplines  above,  a 
large  number  of  other  {octl{2)  calls  apply  to  terminals,  and  have  the  general  form: 

#include  <sgtty.h> 

toctI(fllde8|  codCf  arg) 
struct  sgttyb  "^arg; 
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The  applicable  codes  are: 

TIOCGETP  Fetch  the  basic  parameters  associated  with  the  terminal,  and  store  in  the 
pointed'to  sgttyb  structure. 

TIOCSETP  Set  the  parameters  according  to  the  pointed-to  sgttyb  structure.  The  interface 
delays  until  output  is  quiescent,  then  throws  away  any  unread  characters,  before 
changing  the  modes. 

TIOCSETN  Set  the  parameters  like  TIOCSETP  but  do  not  delay  or  flush  input.  Input  is  not 
preserved,  however,  when  changing  to  or  from  RAW. 

With  the  following  codes  the  arg  is  ignored. 

TIOCEXCL  Set  “exclusive-use”  mode:  no  further  opens  are  permitted  until  the  file  has  been 
closed. 


TIOCNXCL 

TIOCHPCL 

TIOCFLUSH 


Turn  off  “exclusive-use”  mode. 

When  the  file  b  closed  for  the  last  time,  hang  up  the  terminal.  This  is  useful 
when  the  line  is  associated  with  an  ACU  used  to  place  outgoing  calls. 

All  characters  waiting  in  input  or  output  queues  are  flushed. 


The  remaining  calls  are  not  available  in  vanilla  version  7  UNIX.  In  cases  where  arguments  are 
required,  they  are  described;  arg  should  otherwise  be  given  as  0. 

TIOCSTI  the  argument  is  the  address  of  a  character  which  the  system  pretends  was  typed 
on  the  terminal. 


TIOCSBRK 

TIOCCBRK 

TIOCSDTR 

TIOCCDTR 

TIOCGPGRP 

TIOCSPGRP 

FIONREAD 


the  break  bit  is  set  in  the  terminal, 
the  break  bit  is  cleared, 
data  terminal  ready  b  set. 
data  terminal  ready  b  cleared. 

arg  is  the  address  of  a  word  into  which  b  placed  the  process  group  number  of  the 
control  terminal. 

arg  is  a  word  (typically  a  process  id)  which  becomes  the  process  group  for  the 
control  terminal. 

returns  in  the  long  integer  whose  address  is  arg  the  number  of  immediately  read¬ 
able  characters  from  the  argument  unit.  Thb  works  for  files,  pipes,  and  termi¬ 
nals. 


Tchars 

The  second  structure  associated  with  each  terminal  specifies  characters  that  are  special  in  both 
the  old  and  new  terminal  interfaces:  The  following  structure  b  defined  in  <8y$/ioetl.k> ,  which  is 
automatically  included  in  <  sgtty.h^ : 


tehstfs  { 
char  t_lntre( 

/♦  Interrupt  */ 

char 

t_qutte| 

/*  quit  */ 

char 

tjitartc} 

/*  etui  output  */ 

char 

t_Btope) 

/*  atop  output  */ 

char 

t_eof«} 

/•  end-of-flle  */ 

char 

tjbrkei 

/*  Input  delimiter  (like  nl)  */ 

}» 

The  default  values  for  these  characters  are  'C,  ‘\,  *Q,  "S,  *D,  and  -1.  A  character  value  of  -1 
Ajtminafxt  the  cffcct  of  that  character.  The  tjbrkc  character,  by  default  -1,  acts  like  a  new-line  in 
that  it  terminates  a  ‘line,’  b  echoed,  and  is  passed  to  the  program.  The  ‘stop’  and  ‘start’  charac¬ 
ters  may  be  the  same,  to  produce  a  toggle  effect.  It  b  probably  counterproductive  to  make  other 
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special  characters  (including  erase  and  kill)  identical.  The  applicable  ioctl  calls  are: 

TIOCGETC  Get  the  special  characters  and  put  them  in  the  specified  structure. 

TIOCSETC  Set  the  special  characters  to  those  given  in  the  structure. 

Local  mode 

The  third  structure  associated  with  each  terminal  is  a  local  mode  word;  except  for  the 
LNOHANG  bit,  this  word  is  interpreted  only  when  the  new  driver  is  in  use.  The  bits  of  the  local 
mode  word  are; 


LCRTBS 

LPRTERA 

LCRTERA 

LTILDE 

LMDMBUF 

LLITOUT 

LTOSTOP 

LFLUSHO 

LNOHANG 

LETXACK 

LCRTKIL 

LCTLECH 

LPENDIN 

LDECCTQ 


000001  Backspace  on  erase  rather  than  echoing  erase 

000002  Printing  terminal  erase  mode 

000004  Erase  character  echoes  as  backspace-space-backspace 

000010  Convert  to  ^  on  output  (for  Hazeltine  terminals) 

000020  Stop/start  output  when  carrier  drops 

000040  Suppress  output  translations 

000100  Send  SIGTTOU  for  background  output 

000200  Output  is  being  flushed 

000400  Don’t  send  hangup  when  carrier  drops 

001000  Diablo  style  buffer  hacking  (unimplemented) 

002000  BS-space-BS  erase  entire  line  on  line  kill 
010000  Echo  input  control  chars  as  ^X,  delete  as 
020000  Retype  pending  input  at  next  read  or  input  character 
040000  Only  restarts  output  after  ^S,  like  DEC  systems 


The  applicable  ioctl  functions  are: 

TIOCLBIS  arg  is  the  address  of  a  mask  which  is  the  bits  to  be  set  in  the  local  mode  word. 

TIOCT/BIC  arg  is  the  address  of  a  mask  of  bits  to  be  cleared  in  the  local  mode  word. 

TIOCLSET  arg  is  the  address  of  a  mask  to  be  placed  in  the  local  mode  word. 

TIOCLGET  arg  is  the  address  of  a  word  into  which  the  current  mask  is  placed. 

Local  special  chars 


The  final  structure  associated  with  each  terminal  is  the  Itcharo  structure  which  defines  interrupt 
characters  for  the  new  terminal  driver.  Its  structure  is: 


struct  Itch&rs  { 


char 

tjiuspci 

/*  stop  process  signal  */ 

char 

t_dsuspc| 

/*  delayed  stop  process  signal  */ 

char 

t_rprntc| 

/♦  reprint  line  ♦/ 

char 

t_flu8hc; 

/*  flush  output  (toggles)  */ 

char 

t_wera0e| 

/*  word  erase  */ 

char 

tjnextcj 

literal  next  character  */ 

The  default  values  for  these  characters  are  "Y,  ^R,  ^O,  "W,  and  ^V,  A  value  of  -1  disables 
the  character. 

The  applicable  ioctl  functions  are: 

TIOCSLTC  args  is  the  address  of  a  Uchars  structure  which  defines  the  new  local  special  charac¬ 
ters. 

TIOCGLTC  args  is  the  address  of  a  Uchars  structure  into  which  is  placed  the  current  set  of  local 
special  characters. 


Last  change;  17  August  1983 


Sun  Release  1.1 


TTY(4) 


SPECIAL  FILES 


TTY(4) 


FILES 

/dev/tty 

/dev/t^* 

/dev/coBsoIe 

SEE  ALSO 

c»h(l),  8tty(l),  ioctl(2),  8igvec(2),  stty(3C),  geUy(8),  init(8) 

BUGS 

Hstlf-duplex  terminalB  are  not  supported. 
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NAME 

udp  -  Internet  User  Datagram  Protocol 
SYNOPSIS 

None;  comes  automatically  with  incl(4F). 

DESCRIPTION 

The  User  Datagram  Protocol  (UDP)  is  defined  to  make  available  a  datagram  mode  of  packet 
switched  computer  communicaton  in  the  environment  of  an  interconnected  set  of  computer  net¬ 
works.  The  protocol  assumes  that  the  Internet  Protocol  (IP)  as  described  in  ip(4P)  is  used  as  the 
underlying  protocol. 

The  protocol  provides  a  procedure  for  application  programs  to  send  messages  to  other  programs 
with  a  minimum  of  protocol  mechanism.  The  protocol  is  transaction  oriented,  and  delivery  and 
duplicate  protection  are  not  guaranteed.  Applications  requiring  ordered  reliable  delivery  of 
streams  of  data  should  use  the  Transmission  Control  Protocol  (TCP)  as  described  in  tcp{4P). 

The  UNIX  implementation  of  UDP  makes  it  available  as  a  socket  of  type  SOCKJ)GRAM.  UDP 
sockets  are  normally  used  in  a  connectionless  fashion,  with  the  eendto  and  rtcvfrom  calls  described 
in  9end{2)  and  reci;(2). 

A  UDP  socket  is  created  with  a  soeket{2)  call: 

■  =  •ocket(AFJNET,  SOCK^DGRAM,  0)| 

The  socket  initially  has  no  address  associated  with  it,  and  may  be  given  an  address  with  a  itnd(2) 
call  as  described  in  mfl(4F).  If  no  bind  call  is  done,  then  the  address  assignment  procedure 
described  in  inel(4F)  is  repeated  as  each  datagram  is  sent. 

When  datagrams  are  sent  the  system  encapsulates  the  user  supplied  data  with  UDP  and  IP 
headers.  Unless  the  invoker  is  the  super-user  datagrams  which  would  become  broadcast  packets 
on  the  network  to  which  they  are  addressed  are  not  allowed.  Unless  the  socket  has  had  a 
SOJDONTROUTE  option  enabled  (see  80cktt(2))  the  outgoing  datagram  is  routed  through  the 
routing  tables  as  described  in  rsuri*nj7(4N).  If  there  is  insufficient  system  buffer  space  to  tem¬ 
porarily  hold  the  datagram  while  it  is  being  trasmitted,  the  8tndto  may  result  in  a  ENOBUFS 
error.  Other  errors  (ENETUNREACH,  EADDR  NOT  AVAIL,  EACCES,  EMSGSIZE)  may  be  gen¬ 
erated  by  tcmp(4P)  or  by  the  network  interfaces  themselves,  and  are  refiected  back  in  the  send 
call. 

As  each  UDP  datagram  arrives  at  a  host  the  system  strips  out  the  IP  options  and  checksums  the 
data  field,  discarding  the  datagram  if  the  checksum  indicates  that  the  datagram  has  been  dam¬ 
aged.  If  no  socket  exists  for  the  datagram  to  be  sent  to  then  an  ICMP  error  is  returned  to  the 
originating  socket.  If  a  socket  exists  for  this  datagram  to  be  sent  to,  then  we  will  append  the 
datagram  and  the  address  from  which  it  came  to  a  queue  associated  with  the  datagram  socket. 
This  queue  has  limited  capacity  (2048  bytes  of  datagrams)  and  arriving  datagrams  which  will  not 
fit  within  its  capacity  are  silently  discarded. 

UDP  processes  ICMP  errors  refiected  to  it  by  iemp (4P),  QUENCH  errors  are  ignored  (this  is  well 
considered  a  bug);  UNREACH,  TIMXCEED  and  PARAMPROB  errors  cause  the  socket  to  be 
disconnected  from  its  peer  if  it  was  bound  to  a  peer  using  6tnd(2)  so  that  subsequent  attempts  to 
send  datagrams  via  that  socket  will  give  an  error  indication. 

The  UDP  datagram  protocol  differs  from  IP  datagrams  in  that  it  adds  a  checksum  over  the  data 
bytes  and  contains,  a  16-bit  socket  address  on  each  machine  rather  than  just  the  32-bit  machine 
address;  UDP  datagrams  are  addressed  to  sockets;  IP  packets  are  addressed  to  hosts. 

SEE  AJLSO 

recv(2),  send(2),  inet(4F) 

“User  Datagram  Protocol”,  RFC768,  John  Postel,  USC-ISI  (Sun  800-1054-01) 
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BUGS 

SIOCSHIWAT  and  SIOCGHIWAT  ioctrs  to  set  and  get  the  high  water  mark  for  the  socket 
queue,  and  so  that  it  can  be  changed  from  2048  bytes  to  be  larger  or  smaller,  have  been  defined 
(in  <8y8/ioctl.h>)  but  not  implemented. 

Something  sensible  should  be  done  with  QUENCH  errors  if  the  socket  is  bound  to  a  peer  socket. 
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NAME 

vp  -  Ikon  1007L5  Multibus  Versatec  parallel  printer  interface 
SYNOPSIS 

device  vpO  at  mbO  car  0x400  priority  3 
DESCRIPTION 

The  Sun  Multibus  interface  to  the  Versatec  printer/plotter  is  supported  by  the  Ikon  parallel  inter¬ 
face  board,  a  word  DMA  device,  which  is  output  only. 

The  Versatec  is  normally  handled  by  the  line  printer  spooling  system  and  should  not  be  accessed 
by  the  user  directly. 

Opening  the  device  fd^vjvpO  may  yield  one  of  two  errors:  ENXIO  indicates  that  the  device  is 
already  in  use.  EIO  indicates  that  the  device  is  offline. 

The  printer  operates  in  either  print  or  plot  mode.  To  set  the  printer  into  plot  mode  you  should 
include  <vcmd.h>  and  use  the  iocil{2)  call 

ioctl(f,  VSETSTATE,  plotmd); 
where  ploimd  is  defined  to  be 

Int  plotmdl)  =  {  VPLOT,  0,  0  }; 

When  going  back  into  print  mode  from  plot  mode  you  normally  eject  paper  by  sending  it  an  EOT 
after  putting  into  print  mode: 

Int  prtmdQ  =  {  VPRINT,  0,  0  }; 
fflu8h(vp); 

ioctl(f.  VSETSTATE,  prtmd); 
write(f,  ”\04^  1); 

FILES 

/dev/vpO 
SEE  ALSO 

Multibus/Versatec  Interface,  Ikon  Corp  (Includes  Versatec  Manual)  (Sun  S0(^106&-01) 

BUGS 

If  you  use  the  standard  i/o  library  on  the  Versatec,  be  sure  to  explicitly  set  a  buffer  using  seihuf, 
since  the  library  will  not  use  buffered  output  by  default,  and  will  run  very  slowly. 

This  driver  is  not  supported. 

Writes  must  start  on  even  byte  boundaries  and  be  an  even  number  of  bytes  in  length. 
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NAME 

vpc  -  Systech  VPC-2200  Versatec  printer/plotter  and  Centronics  printer  interface 
SYNOPSIS 

device  vpeO  at  mbO  ear  0x480  priority  2 
DESCRIPTION 

The  Sun  Multibus  interface  to  the  Versatec  printer/plotter  and  to  Centronics  printers  is  sup¬ 
ported  by  the  Systech  parallel  interface  board,  an  output-only  byte-wide  DMA  device.  The  device 
has  one  channel  for  Versatec  devices  and  one  channel  for  Centronics  devices,  with  an  optional 
long  lines  interface  for  Versatec  devices. 

Devices  attached  to  this  interface  are  normally  handled  by  the  line  printer  spooling  system  and 
should  not  be  accessed  by  the  user  directly. 

Opening  the  devices  JdtvfvpO  {devflpO  may  yield  one  of  two  errors:  ENXIO  indicates  that  the 
device  is  already  in  use.  EIO  indicates  that  the  device  is  offline. 

The  Versatec  printer/plotter  operates  in  either  print  or  plot  mode.  To  set  the  printer  into  plot 
mode  you  should  include  <vcmd.h>  and  use  the  iocU{2)  call: 

ioctl(f,  VSETSTATE,  plotmd); 

where  plotmd  is  defined  to  be 

Int  plotmdO  =  {  VPLOT,  0,  0  }; 

When  going  back  into  print  mode  from  plot  mode  you  normally  eject  paper  by  sending  it  an  EOT 
after  putting  into  print  mode: 

lat  prtmdl  1  =■  {  VPRINT,  0,  0  }; 
ffluBh(vpc); 

ioctl(f,  VSETSTATE,  prtmd); 
write(f,  ’’\04’’,  1); 

FILES 

/dev/vpO 

/dev/lpO 

SEE  ALSO 

Systech  VPC-2200  Versatec  Printer/Plotter  Controller  Technical  Manual 

BUGS 

If  you  use  the  standard  I/O  library  on  the  Versatec,  be  sure  to  explicitly  set  a  buffer  using  eetbuf, 
since  the  library  will  not  use  buffered  output  by  default,  and  will  run  very  slowly. 

Currently  only  8  bit  I/O  is  supported  in  the  driver,  even  though  the  device  supports  16  bit  I/O. 
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NAME 

win  -  Sun  window  system 
SYNOPSIS 

pseudo-device  win  128 
pseudo-device  dtop4 

DESCRIPTION 

The  win  device  accesses  the  system  drivers  supporting  the  Sun  window  system. 

Each  window  in  the  system  is  represented  by  a  /dev/win*  device.  The  windows  are  organized  as 
a  tree  with  windows  being  subwindows  of  their  parents,  and  covering/covered  by  their  siblings. 
Each  window  has  a  position  in  the  tree,  a  position  on  a  display  screen,  an  input  queue,  and  infor¬ 
mation  telling  what  parts  of  it  are  exposed. 

The  window  driver  multiplexes  keyboard  and  mouse  input  among  the  several  windows,  tracks  the 
mouse  with  a  cursor  on  the  screen,  provides  each  window  access  to  information  about  what  parts 
of  it  are  exposed,  and  notifies  the  manager  process  for  a  window  when  the  exposed  area  of  the 
window  changes  so  that  the  window  may  repair  its  display. 

The  dtop4  pseudo  device  line  in  a  kernel  configuration  file  indicates  the  number  of  separate 
^^desktops’’  (frame  buffers)  that  can  be  actively  running  the  Sun  window  system  at  once. 

Full  information  on  the  window  system  functions  is  given  in  the  Programmer's  Reference  Manual 
for  SunWindows, 

PILES 

/dcv/win(0-9) 

/dev  /  win  [0-9]  (0-9) 

SEE  ALSO 

Programmer's  Reference  Manual  for  SunWindows 
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NAME 

xy  -  Disk  driver  for  Xy  logics  SMD  Disk  Coatrollers 
SYNOPSIS 

controller  xycO  at  mbO  esr  0xee40  priority  2 
disk  xyO  at  xycO  drive  0 
disk  xyl  at  xycO  drive  1 

DESCRIPTION 

Files  with  minor  device  numbers  0  through  7  refer  to  various  portions  of  drive  0;  minor  devices  8 
through  15  refer  to  drive  1,  and  so  on.  The  standard  device  names  begin  with  *^xy”  followed  by 
the  drive  number  and  then  a  letter  a-h  for  partitions  0-7  respectively.  The  character  ?  stands 
here  for  a  drive  number  in  the  range  0^7. 

The  block  file’s  access  the  disk  via  the  system’s  normal  buffering  mechanism  and  may  be  read  and 
written  without  regard  to  physical  disk  records.  There  is  ako  a  'raw’  interface  which  provides  for 
direct  transmission  between  the  disk  and  the  user’s  read  or  write  buffer.  A  single  read  or  write 
call  results  in  exactly  one  I/O  operation  and  therefore  raw  I/O  is  considerably  more  effficient 
when  many  words  ate  transmitted.  The  names  of  the  raw  files  conventionally  begin  with  an  extra 
'r.’ 

In  raw  I/O  counts  should  be  a  multiple  of  512  bytes  (a  disk  sector).  Likewise  seek  calls  should 
specify  a  multiple  of  512  bytes. 

DISK  SUPPORT 

This  driver  handles  all  SMD  drives,  by  reading  a  label  from  sector  0  of  the  drive  which  describes 
the  disk  geometry  and  partitioning. 

The  xyfa  partition  is  normally  used  for  the  root  file  system  on  a  disk,  the  xy?b  partition  as  a  pag¬ 
ing  area,  and  the  xyTc  partition  for  pack-pack  copying  (it  normally  maps  the  entire  disk).  The 
rest  of  the  disk  is  normally  the  xy?h  partition. 

FILES 

/dcv/xy(0-7]|>hj  block  files 

/dev/rxy[0-7|(a-hj  raw  files 

SEE  ALSO 

dkio(4S),  xy(4S) 

Xylogics  Model  440  Peripheral  Processor  SMD  Disk  Subsystem  Maintenance  and  Reference 
Manual  (Sun  800-1005-01) 

Xy  logics  Model  450  Peripheral  Processor  SMD  Disk  Subsystem  Maintenance  and  Reference 
Manual  (Sun  800-1025-01) 

DIAGNOSTICS 

xyc%d%  self  tent  error  %x  -  %b.  Self  test  error  in  controller,  see  the  Maintenance  and  Refer¬ 
ence  Manual, 

xyc%ds  addreai  mode  Jumper  la  wrong.  The  controller  is  strapped  for  24-bit  Multibus 
addresses;  the  Sun  uses  20-bit  addresses.  See  the  Hardware  Configuration  and  Expansion  section 
of  the  System  Manager's  Manual  for  your  Sun  Workstaiton  for  instructions  on  setting  the  jumpers 
on  the  450. 

xyattachi  ean^t  get  bad  sector  info.  The  bad  sector  forwarding  information  for  the  disk, 
which  is  kept  on  the  last  cylinder,  could  not  be  read. 

xy%di  drive  type  %d  clash  with  xy%d.  The  450  does  not  support  mixing  the  drive  types 
found  on  these  units  on  a  single  controller. 

xy%ds  initialisation  fidled. 
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xy%dt  error  9Sx  reading  label  on  head  %d.  Error  reading  drive  geometry/partition  table 
information. 

xy%dt  Corrupt  label.  The  geometry/partition  label  checksum  was  incorrect. 
xy%dt  Unsupported  phys  partition  #  %d. 
xy%d:  ofiiine. 

xy%d%ct  cmd  how  (mog)  blk  %d.  A  command  such  as  read,  write,  or  format  encountered  a 
error  condition  (how):  either  it  failed,  the  unit  was  restored,  or  an  operation  was  refried.  The 
msg  is  derived  from  the  error  number  given  by  the  controller,  indicating  a  condition  such  as 
“drive  not  ready”,  “sector  not  found”  or  “disk  write  protected”. 

BUGS 

In  raw  I/O  read  and  write{2)  truncate  file  offsets  to  S12*byte  block  boundaries,  and  write  scribbles 
on  the  tail  of  incomplete  blocks.  Thus,  in  programs  that  are  likely  to  access  raw  devices,  read, 
write  and  l8eek{2)  should  always  deal  in  512>byte  multiples. 
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NAME 

15  -  zilog  8530  see  serial  comunications  driver 
SYNOPSIS 

device  zsO  at  mbO  ear  OxfSaOOO  flags  3  priority  5 
DESCRIPTION 

The  Zilog  8530  provides  2  serial  communication  lines  with  full  modem  control.  Each  line  behaves 
as  described  in  rip(4).  Input  and  output  for  each  line  may  independently  be  set  to  run  at  any  of 

16  speeds;  see  rip(4)  for  the  encoding. 

FILES 

/dcv/tty[a-dl 

SEE  ALSO 
tty(4) 

Zilog  Z8030/Z8530  SCO  Serial  Communications  Controller  (Sun  800>1052>01) 

DIAGNOSTICS 

n%d%ct  silo  overflow.  The  character  input  silo  overflowed  before  it  could  be  serviced. 
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NAME 

a.out  -  assembler  and  link  editor  output 

SYNOPSIS 

#include  <a*out.h> 

#include  <stab.h> 

#include  <nUflt«h> 

DESCRIPTION 

A,oui  is  the  output  file  of  the  assembler  ss(lS)  and  the  link  editor  /d(l). 
executable  if  there  were  no  errors  and  no  unresolved  external  references, 
given  in  the  include  file  for  the  Sun  system  is: 

/* 

^  Header  prepended  to  each  a.out  file. 

*1 

struct  exec  { 


The  latter  makes  a, out 
Layout  information  as 


long 

a_magic; 

/* 

unsigned 

a_text; 

r 

unsigned 

a.data; 

/* 

unsigned 

a_b85; 

!* 

unsigned 

ajsyms; 

/* 

unsigned 

a_entry; 

/* 

unsigned 

ajtrsize; 

/* 

}; 

unsigned 

ajdrsize; 

/* 

#deflne 

OMAGIC  0407 

/* 

#define 

NMAGIC  0410 

f* 

#define 

ZMAGIC  0413 

i* 

^define 

PAGSIZ 

2048 

#define 

SEGSIZ 

0x8000 

#defiDC 

TXTRELOC  SEGSIZ 

size  of  initialized  data  */ 


r 

*  Macroa  which  take  exec  structures  as  arguments  and  tell  whether 

*  the  file  has  a  reasonable  magic  number  or  offsets  to  text  |  symbols  |  strings. 

V 

#define  N_3ADMAG(x)  \ 

(((x).ajnagic)f=OMAGIC  &&  ((x).a_magic)!=NMAGIC  &&  ((x).a_magic)!=ZMAGIC) 


#define  N_TXTOFr(x)  \ 

((x)*a_niagic==ZMAGIC  ?  PAGSIZ  :  sizeof  (struct  exec)) 
fdefine  N_SYMOFF(x)  \ 

(N_TXTOFF(x)  +  (x).a_text+  (x).a_data  +  (x).a_trsize+  (x).a_dr8ize) 
#define  nJtROFF(x)  \ 

(N_SYMOFF(x)  +  (x).a_6ym8) 

/* 

*  Macros  which  take  exec  structures  as  arguments  and  tell  where  the 

*  various  pieces  will  be  loaded. 

•/ 

#define  N_TXTADDR(x)  TXTRELOC 
#define  N_DATADDR(x)  \ 

({(x).a_magic==OMAGIC)?  (N_TXTADDR(x)+  (x).a_text)  \ 

:  (SEGSIZ+((N_TXTADDR(x)+(x).a_text-l)  &  'SEGRND))) 
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#define  N_BSSADDR(x)  (N^DATADDR(x)+  (x).ajata) 

The  a, out  file  has  five  sections:  a  header,  the  program  text  and  data,  relocation  information,  a 
symbol  table  and  a  string  table  (In  that  order).  The  last  three  may  be  omitted  if  the  program  was 
loaded  with  the  -s'  option  of  Id  or  if  the  symbols  and  relocation  have  been  removed  by  s^np(l). 

In  the  header  the  sizes  of  each  section  are  given  in  bytes.  The  size  of  the  header  is  not  included 
in  any  of  the  other  sizes. 

When  an  a, out  file  is  executed,  three  logical  segments  are  set  up:  the  text  segment,  the  data  seg¬ 
ment  (with  uninitialized  data,  which  starts  off  as  all  0,  following  initialized  data),  and  a  stack. 
The  header  is  not  loaded  with  the  text  segment.  If  the  magic  number  in  the  header  is  OMAGIC 
(0407),  it  means  that  this  is  a  non-sbarable  text  which  is  not  to  be  write-protected,  so  the  data 
segment  is  immediately  contiguous  with  the  text  segment.  This  is  rarely  used.  If  the  magic 
number  is  NMAGIC  (0410)  or  ZMAGIC  (0413),  the  data  segment  begins  at  the  first  segment 
boundary  following  the  text  segment,  and  the  text  segment  is  not  writable  by  the  program;  other 
processes  executing  the  same  file  will  share  the  text  segment.  For  ZMAGIC  format,  the  text  seg¬ 
ment  begins  on  a  page  boundary  in  the  a,oui  file;  the  remaining  bytes  after  the  header  in  the  first 
block  are  reserved  and  should  be  zero.  In  this  case  the  text  and  data  sizes  must  both  be  multiples 
of  the  page  size,  and  the  pages  of  the  file  will  be  brought  into  the  running  image  as  needed,  and 
not  pre-loaded  as  with  the  other  formats.  This  is  especially  suitable  for  very  large  programs  and 
is  the  default  format  produced  by  W(l).  The  macros  NJTXTADDR,  NJ>ATADDR,  and 
NJ3SSAODR  give  the  core  addresses  at  which  the  text,  data,  and  bss  segments,  respectively,  will 
be  loaded. 

The  stack  starts  at  the  highest  possible  location  in  the  memory  image,  and  grows  downwards. 
The  stack  is  automatically  extended  as  required.  The  data  segment  is  extended  as  requested  by 
hrk{2)  or  ebrk{2). 

After  the  header  in  the  file  follow  the  text,  data,  text  relocation  data  relocation,  symbol  table  and 
string  table  in  that  order.  The  text  begins  at  byte  PAGSIZ  in  the  file  for  ZMAGIC  format  or  just 
after  the  header  for  the  other  formats.  The  N_TXTOFF  macro  returns  this  absolute  file  position 
when  given  the  name  of  an  exec  structure  as  argument.  The  data  segment  is  contiguous  with  the 
text  and  immediately  followed  by  the  text  relocation  and  then  the  data  relocation  information. 
The  symbol  table  follows  all  this;  its  position  is  computed  by  the  N_SYMOFF  macro.  Finally, 
the  string  table  immediately  follows  the  symbol  table  at  a  position  which  can  be  gotten  easily 
using  N_STROFF,  The  first  4  bytes  of  the  string  table  are  not  used  for  string  storage,  but  rather 
contain  the  size  of  the  string  table;  this  size  INCLUDES  the  4  bytes,  the  minimum  string  table 
size  is  thus  4. 

RELOCATION 

The  value  of  a  byte  in  the  text  or  data  which  is  not  a  portion  of  a  reference  to  an  undefined 
external  symbol  is  exactly  that  value  which  will  appear  in  memory  when  the  file  is  executed.  If  a 
byte  in  the  text  or  data  involves  a  reference  to  an  undefined  external  symbol,  as  indicated  by  the 
relocation  information,  then  the  value  stored  in  the  file  is  an  offset  from  the  associated  external 
symbol.  When  the  file  is  processed  by  the  link  editor  and  the  external  ^mbol  becomes  defined, 
the  value  of  the  symbol  is  added  to  the  bytes  in  the  file. 

If  relocation  information  is  present,  it  amounts  to  eight  bytes  per  relocatable  datum  as  in  the  fol¬ 
lowing  structure: 

r 

*  Format  of  a  relocation  datum. 

V 

struct  relocationjnfo  { 

int  r_address;  /*  address  which  is  relocated  */ 
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unsigned  r_symboInum:24, 
r_pcrel:l, 
rjengtb:2, 
r_extern:l, 

*4* 


/*  local  symbol  ordinal  */ 

/*  was  relocated  pc  relative  already  */ 

/*  0=byte,  l=word,  2=long  */ 

/*  does  not  include  value  of  sym  referenced  */ 
I*  nothing,  yet  ♦/ 


There  is  no  relocation  information  if  a_tr8ize+  a_dr8ize==0.  If  r^extern  is  0,  then  r^symbolnum 
is  actually  a  n^typc  for  the  relocation  (i.e.  N^TEXT  meaning  relative  to  segment  text  origin.) 


SYMBOL  TABLE 


The  layout  of  a  symbol  table  entry  and  the  principal  flag  values  that  distinguish  symbol  types  are 
given  in  the  include  file  as  follows: 


*n_name;  /*  for  use  when  in-memory  */ 
n_8trx;  /*  index  into  file  string  table  */ 


r 

*  Format  of  a  ^mbol  table  entry. 

V 

struct  nlist  { 

union  { 
char 
long 
}  n_un; 

unsigned  char  njtype; 


char 

D_other; 

short 

n_desc; 

unsigned 

Devalue; 

#defiiie  n.bash 

ii_desc 

/* 

*  Simple  values  for 

n_type. 

V 

#deflne  N_UNDF 

QxO 

#define  N_ABS 

Qx2 

#define  N.TEXT 

0x4 

#define  N_DATA 

0x6 

#define  NJBSS 

0x8 

#define  N.COMM 

0x12 

#deflne  NJFN 

Oxlf 

#define  N^XT 

01 

#deflne  N.TYPE 

Oxle 

/♦  type  flag,  i.e.  NJTEXT  etc;  see  below 
f*  see  <stab.h>  */ 

/*  value  of  this  symbol  (or  adb  offset)  ♦/ 
/*  used  internally  by  Id  */ 


/*  undefined  */ 

/*  absolute  */ 

/♦  text  */ 

/*  data  */ 
bss 

/*  common  (internal  to  Id)  */ 
/*  file  name  symbol  */ 

/*  external  bit,  or’ed  in 
/♦  mask  for  all  the  type  bits  */ 


V 


/* 

•  Other  permanent  symbol  table  entries  have  some  of  the  N_STAB  bits  set. 

*  These  are  given  in  <8tab.h> 

V 

#define  N_STAB  "  OxeO  /*  if  any  of  these  bits  set,  don’t  discard  */ 

In  the  a,out  file  a  Q^mbol’s  n_un.n_8trx  field  gives  an  index  into  the  string  table.  A  njstrx  value 
of  0  indicates  that  no  name  is  associated  with  a  particular  qrmbol  table  entry.  The  field 
n_un.n_name  can  be  used  to  refer  to  the  symbol  name  only  if  the  program  sets  this  up  using 
n_8trx  and  appropriate  data  from  the  string  table.  Because  of  the  union  in  the  nlist  declaration, 
it  is  impossible  in  C  to  statically  initialize  such  a  structure.  If  this  must  be  done  (as  when  using 
n/tsl(3))  the  file  <nll8t.h>  should  be  included,  rather  that  <a.out.h>;  this  contains  the 
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declaration  without  the  union. 

If  a  symbol’s  type  is  undefined  external,  and  the  value  field  is  non-zero,  the  symbol  is  interpreted 
by  the  loader  Id  as  the  name  of  a  common  region  whose  size  is  indicated  by  the  value  of  the  sym¬ 
bol. 

STAB  SYMBOLS 

Stab.h  defines  some  values  of  the  n_type  field  of  the  symbol  table  of  a.out  files.  These  are  the 
types  for  permanent  symbols  (that  is,  not  local  labels,  etc.)  used  by  the  debuggers  aif6(lS)  and 
dbx{l)  and  the  Berkeley  Pascal  compiler  pc(l).  Symbol  table  entries  can  be  produced  by  the 
.stabs  assembler  directive.  This  allows  one  to  specify  a  double-quote  delimited  name,  a  q^mbol 
type,  one  char  and  one  short  of  information  about  the  symbol,  and  an  unsigned  long  (usually  an 
address).  To  avoid  having  to  produce  an  explicit  label  for  the  address  field,  the  .stabd  directive 
can  be  used  to  implicitly  address  the  current  location.  If  no  name  is  needed,  symbol  table  entries 
can  be  generated  using  the  .stabn  directive.  The  loader  promises  to  preserve  the  order  of  ^mbol 
table  entries  produced  by  .stab  directives. 

The  n_value  field  of  a  symbol  is  relocated  by  the  link  editor  as  an  address  within  the  appropriate 
segment.  N_value  fields  of  symbols  not  in  any  segment  are  unchanged  by  the  linker.  In  addition, 
the  linker  will  discard  certain  symbols,  according  to  rules  of  its  own,  unless  the  n_type  field  has 
one  of  the  bits  masked  by  N_STAB  set. 

This  allows  up  to  112  (7  *  16)  symbol  types,  split  between  the  various  segments.  Some  of  these 
have  already  been  claimed.  The  debugger,  ad((lS),  uses  the  following  n_type  values; 

#define  N_GSYM  0x20  /*  global  symbol:  name„0,type,0  */ 

#define  N_FNAME  0x22  /*  procedure  name  (f77  kludge):  name„0  */ 

#define  N_FUN  0x24  /*  procedure:  name„0,linenumber,address  */ 

#define  N_STSYM  0x26  /*  static  symbol:  name„0,type,addre8s  *f 
#define  N_LCSYM  0x28  /•  .Icomm  symbol:  name„0,type, address  ♦/ 

#define  N_RSYM  0x40  /*  register  sym:  name„0, type, register  */ 

^define  N_SLINE  0x44  /*  src  line:  0„0,linenumber,address  */ 

#define  N_SSYM  0x60  f*  structure  elt:  name„0,type,struct_offset  */ 

#define  N_SO  0x64  f*  source  file  name:  name„0,0,addre8S  */ 

#define  N_LSYM  0x80  /*  local  sym:  name„0,type,offset  */ 

#define  N_SOL  0x84  /*  ^included  file  name;  name„0,0,address  */ 

#define  NJ’SYM  QxaO  /*  parameter:  name„0, type, offset  */ 

#define  N_ENTRY  0xa4  f*  alternate  entry:  name,linenumber,addre8s  */ 

#deflne  N_LBRAC  OxcO  /•  left  bracket:  0„0,nesting  level, address  */ 

^define  N_RBRAC  OxeO  /*  right  bracket:  0„0, nesting  level.address  */ 

#define  N_BCOMM0xe2  /*  begin  common:  name,,  */ 

#define  NJECOMM0xe4  /*  end  common:  name,,  */ 

#define  N_ECOML  0xe8  /*  end  common  (local  name):  „address  •/ 

#define  N_LENG  Oxfe  /*  second  stab  entry  with  length  information  */ 

where  the  comments  give  the  adb  conventional  use  for  .stabs  and  the  n  name,  n  other,  n  desc 
and  n_value  fields  of  the  given  n_type.  Adb  uses  the  n.desc  field  to  hold  a  type  specifier  i^  the 
form  used  by  the  Portable  C  Compiler,  cc(l),  in  which  a  base  type  is  qualified  in  the  following 
structure: 

struct  desc  { 

short  q6:2, 
q5:2, 
q4:2,  . 

q3;2, 
q2:2, 
ql:2. 
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ba8ic:4; 

}; 

There  are  four  qualifications,  with  ql  the  most  significant  and  q6  the  least  significant: 

0  none 

1  pointer 

2  function 

3  array 

The  sixteen  basic  types  are  assigned  as  follows: 

0  undefined 

1  function  argument 

2  character 

3  short 

4  int 

5  long 

6  float 

7  double 

8  structure 

9  union 

10  enumeration 

11  member  of  enumeration 

12  unsigned  character 

13  unsigned  short 

14  unsigned  int 

15  unsigned  long 

The  Berkeley  Pascal  compiler,  j?c(l),  uses  the  following  n_type  value: 

#deflne  N J^C  0x30  f*  global  pascal  symbol:  name„0, subtype, line  */ 

and  uses  the  following  subtypes  to  do  type  checking  across  separately  compiled  files: 

1  source  file  name 

2  included  file  name 

3  global  label 

4  global  constant 

5  global  type 

6  global  variable 

7  global  function 

8  global  procedure 

0  extern^  function 

10  external  procedure 

11  library  variablii 

12  library  routine 

The  new  dbx(l)  debugger  uses  an  entirely  different  interpretation  for  the  etaba  symbol-table 
entries.  Currently,  this  is  understood  only  by  dbx  and  cc,  but  its  use  should  supplant  the  current 
interpretation  as  soon  as  adb  and  pc  can  1^  modified  to  use  it. 

SEE  ALSO 

adb(lS),  as(lS),  ld(l);  nm(l),  dbx(l),  8trip(l) 

BUGS 

There  are  currently  two  interpretations  of  the  stabs  symbol-table  information.  This  creates  great 
confusion  when  trying  to  build  a  program  for  debugging. 

Due  to  the  amount  of  symbolic  information  necessary  for  high-level  debugging,  the  whole  a.  cut 
structure  has  been  streched  well  beyond  its  original  design,  and  should  be  replaced  by  something 
with  a  more  sophisticated  symbol-table  mechanism.  The  demands  of  future  languages  will  only 
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NAME 

aliases  -  aliases  file  for  sendmail 

SYNOPSIS 

/usr/Ub/aliases 
/usr /Ilb/alla8e8.dlr 
/usr/lib/idlases.pag 

DESCRIPTION 

These  files  describe  user  id  aliases  used  by  /usr//t6/scndm(xt7,  /usr/Kft/oKasca  is  formatted  as  a 
series  of  lines  of  the  form 

name:  name_l,  iiame2,  namej3, .  ,  . 

The  name  is  the  name  to  alias,  and  the  namc^n  are  the  aliases  for  that  name.  Lines  beginning 
with  white  space  are  continuation  lines.  Lines  beginning  with  ‘  #  *  are  comments. 

Aliasing  occurs  only  on  local  names.  Loops  can  not  occur,  since  no  message  will  be  sent  to  any 
person  more  than  once. 

After  aliasing  has  been  done,  local  and  valid  recipients  who  have  a  “.forward”  file  in  their  home 
directory  have  messages  forwarded  to  the  list  of  users  defined  in  that  file. 

fusrjliblaliaeea  is  only  the  raw  data  file;  the  actual  aliasing  information  is  placed  into  a  binary 
format  in  the  files  f  usrllibj adaseeJir  2iJii  fusrllibfaHases^pag  using  the  program  nc«;a/iasea(8).  A 
newaliasea  command  should  be  executed  each  time  that  fustfUbf  aliases  is  changed  for  the  change 
to  take  effect. 

Several  kinds  of  name's  are  special: 
owner^mary:  fred 

any  errors  resulting  from  a  mail  to  maty  are  directed  to  fred  instead  of  back  to  the  person 
who  sent  the  message.  This  is  most  useful  when  mary  is  a  mailing  list  rather  than  an 
individual. 

beer:  :include:/u8r/cyndi/beer; 

All  colons  and  semicolons  are  required  as  shown.  The  list  of  names  in  lusrfcyndijbeer  is 
included  in  the  namejn  list  for  the  beer  alias,  in  addition  to  any  other  names  in  the 
namejn  list.  This  mechanism  is  for  setting  up  a  mailing  list  so  that  j usrf  lib f  aliases 
doesn't  have  to  be  changed  when  people  are  added  to  or  removed  from  the  list.  The 
included  file  (that  is,  j  usrf  cyndij  beer  in  this  case)  may  be  changed  at  any  time,  and 
changes  take  effect  immediately. 

SEE  ALSO 

newatia8es(8),  dbm(3X)^  8endmail(8) 

SENDMAIL  Installation  and  Operation  Guide. 

SENDK^IL  An  Internetwork  Mail  Router. 

BUGd 

Because  of  restrictions  in  d6m(3X)  a  single  alias  cannot  contain  more  than  about  1000  bytes  of 
information.  You  can  get  longer  aliases  by  “chaining”;  that  is,  make  the  last  name  in  the  alias  be 
a  dummy  name  which  is  a  continuation  alias. 
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NAME 

ar  -  archive  (library)  file  format 

SYNOPSIS 

#include  <ar.h> 

DESCRIPTION 

The  archive  command  ar  combines  several  files  into  one*  Archives  are  used  mainly  as  libraries  to 
be  searched  by  the  link*editor  W. 

A  file  produced  by  ar  has  a  magic  string  at  the  start,  followed  by  the  constituent  files,  each  pre¬ 
ceded  by  a  file  header*  The  magic  number  and  header  layout  as  described  in  the  include  file  are: 

/♦  ®(#)ar.h  LI  83/08/01  SMI;  from  UCB  4*1  83/05/03*/ 

#defineARMAG  ”!<arch>\n” 

#define  SARMAG  8 

#define  ARFMAG  ”‘\n’* 

struct  ar_hdr  { 

char  ar_name[l6]; 

char  ar_date[12|; 

char  ar_uid[6j; 

char  ar_^id(6j; 

char  ar_mode[8); 

char  ar_6ize[l0|; 

char  ar  fmag[2]; 

}; 

The  name  is  a  blank-padded  string.  The  (ir_fmag  field  contains  ARFMAG  to  help  verify  the  pres¬ 
ence  of  a  header.  The  other  fields  are  left-adjusted,  blank-padded  numbers.  They  are  decimal 
except  for  ar_mode,  which  is  octal.  The  date  is  the  modification  date  of  the  file  at  the  time  of  its 
insertion  into  the  archive. 

Each  file  begins  on  a  even  (0  mod  2)  boundary;  a  new-line  is  inserted  between  files  if  necessary. 
Nevertheless  the  size  given  reflects  the  actual  size  of  the  file  exclusive  of  padding. 

There  is  no  provision  for  empty  areas  in  an  archive  file. 

The  encoding  of  the  header  is  portable  across  machines.  If  an  archive  contains  printable  files,  the 
archive  itself  is  printable. 

SEE  ALSO 

ar(l),  ld(l),  nm(l) 

BUGS 

File  names  lose  trailing  blanks.  Most  software  dealing  with  archives  takes  even  an  included  blank 
as  a  name  terminator* 
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NAME 

core  -  format  of  memory  image  file 
SYNOPSIS 

#includ€  <  machine/par am.h> 

DESCRIPTION 

The  UNIX  System  writes  out  a  memory  image  of  a  terminated  process  when  any  of  various  errors 
occur <  See  8igvec{2)  for  the  list  of  reasons;  the  most  common  are  memory  violations,  illegal 
instructions,  bus  errors,  and  user^generated  quit  signals.  The  memory  image  is  called  ‘core’  and  is 
written  in  the  process’s  working  directory  (provided  it  can  be;  normal  access  controls  apply). 

The  maximum  size  of  a  core  file  is  limited  by  Beirlimit(i).  Files  which  would  be  larger  than  the 
limit  are  not  created. 

Set-user*id  programs  do  not  produce  core  files  when  they  terminate  as  this  would  be  a  security 
loophole. 

The  core  file  consists  of  the  u.  area,  whose  size  (in  pages)  is  defined  by  the  UP  AGES  manifest  in 
the  <mackinel param,h>  file.  The  u.  area  starts  with  a  user  structure  as  given  in 
<sys/user.A>.  The  remainder  of  the  core  file  consists  first  of  the  data  pages  and  then  the  stack 
pages  of  the  process  image.  The  amount  of  data  space  image  in  the  core  file  is  given  (in  pages)  by 
the  variable  u_dsize  in  the  u.  area.  The  amount  of  stack  image  in  the  core  file  is  given  (in  pages) 
by  the  variable  ujssizt  in  the  u.  area. 

SEE  ALSO 

adb(l),  dbx(l),  sigvec(2),  8etrlimit(2) 
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NAME 

cpio  -  format  of  cpio  archive 
DESCRIPTION 

The  old  format  header  structure,  when  the  c  option  is  not  used,  is: 

Btruct  { 

short  h^magic, 
h_dev, 
hjno, 
h_mode, 
h_uid, 
h_gid, 
h.nlink, 
h_r{lev, 
h_mtiine(2j, 
h_namesize, 
h_filesize[2]; 

char  h_&aine(h  namesize  rounded  to  a  word]; 

}Hdr; 

but  note  that  the  bjrte  order  here  is  that  of  the  PDP-U  and  the  VAX,  and  that  for  the  Sun  you 
have  to  use  swa((3)  after  reading  and  before  writing  heatders, 

When  the  c  option  is  used,  the  header  information  is  described  by  the  statement  below: 

68canf(Chdr,  ”%6o%6o%6o%6o%6o%6o%6o%6o%lllo%6o%6o%8", 

&Hdr.h_magic,  &Hdr.h_dev,  &Hdr.hjlno,  &Hdr.h_mode, 

&Hdr.h_uid,  &Hdr.h_gid,  &Hdr.h_nHnk,  &Hdr.h_rdev, 

&Hdr,h_mtime,  &Hdr.h_nameBize,  &Hdr.h_fiIesize,  &Hdr.h_name); 

Longtime  and  LongfUe  are  equivalent  to  Hdr.h_mtime  and  Hdr.hJUesize,  respectively.  The  con¬ 
tents  of  each  file  is  recorded  in  an  element  of  the  array  of  varying  length  structures,  archive, 
together  with  other  items  describing  the  file.  Every  instance  of  hjnagic  contains  the  constant 
070707  (octal).  The  items  h_dev  through  hjmtime  have  meanings  explained  in  9tat{2).  The 
length  of  the  null-terminated  path  name  h_name,  including  the  null  byte,  is  given  by  h^namesize. 

The  last  record  of  the  archive  always  contains  the  name  TRAILER!!!.  Special  files,  directories, 
and  the  trailer,  are  recorded  with  hjilesize  equal  to  zero. 

SEE  ALSO 

Gpio(l),  find(l),  8tat(2) 
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NAME 

crontab  -  table  of  times  to  run  periodic  jobs 
DESCRIPTION 

The  letcjcron  utility  is  a  permanent  process,  started  by  j  eicIrcAocai,  that  wakes  up  once  every 
minute,  j  tic j cron  consults  the  file  luerjlihlcrontah  to  find  out  what  tasks  are  to  be  done,  and  at 
what  time. 

Each  line  in  futrUihl crontab  consists  of  six  fields,  separated  by  spaces  or  tabs,  as  follows: 

1.  minutes  field,  which  can  have  values  in  the  range  0  through  59. 

2.  hours  field,  which  can  have  values  in  the  range  0  through  23. 

3.  day  of  the  month,  in  the  range  1  through  31. 

4.  month  of  the  year,  in  the  range  1  through  12. 

5.  day  of  the  week,  in  the  range  1  through  7.  Monday  is  day  1  in  this  scheme  of  things. 

6.  (the  remainder  of  the  line  )  is  the  command  to  be  run.  A  percent  character  in  this  field  is 

translated  to  a  new-line  character.  Only  the  first  line  (up  to  a  %  or  end  of  line)  of  the 
command  field  is  executed  by  the  Shell.  The  other  lines  are  made  available  to  the  com¬ 
mand  as  standard  input. 

Any  of  fields  1  through  6  can  be  a  list  of  values  separated  by  commas.  A  field  can  be  a  pair  of 
numbers  separated  by  a  hyphen,  indicating  that  the  job  is  to  be  done  for  all  the  times  in  the 
specified  range.  If  a  field  is  an  asterisk  character  (’*‘)  it  means  that  the  job  is  done  for  all  possible 
values  of  the  field. 

FILES 

/usr/lib/crontab 

SEE  ALSO 

croD(8),  rc(8) 

EXAMPLE 

0  0  ♦  ♦  *  calendar  - 

16  0  *  *  *  /etc/sa-s  >/dev/null 

16  4  •  *  *  find  /usr/preserve  -mtime  +  7  -a  -exec  rm  -f  {}  ; 

40  4  •  •  *  find  /  -name  -atime  +  3  -excc  rm  -f  {}  ; 

0,16,30,46  ♦  *  ♦  *  /etc/atrun 

0,10,20,30,40,50  ♦  ♦  ♦  ♦  /etc/dmesg  -  >>/usr/adm/me8sage8 
5  4  •  •  •  sh  /etc/newsyslog 

The  calendar  command  run  at  minute  0  of  hour  0  (midnight)  of  every  day.  The  /efc/sa  command 
runs  at  16  minutes  after  midnight  every  day.  The  two  find  commands  run  at  15  minutes  past 
four  and  at  40  minutes  past  four,  respectively,  every  day  of  the  year.  The  atrun  command  (which 

processes  shell  scripts  users  have  set  up  with  at)  runs  every  15  minutes.  The  fetcldmesg  com¬ 

mand  appends  kernel  messages  to  the  f  uer/ adm/ meesages  file  every  ten  minutes,  and  finally,  the 
f  uerf  adm! eytlog  script  runs  at  five  minutes  after  four  every  day. 
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NAME 

dir  -  format  of  directories 
SYNOPSIS 

#lnclude  <8yB/typeB.h> 

#inelude  <ByB/dIr.h> 

DESCRIPTION 

A  directory  behaves  exactly  like  an  ordinary  file,  save  that  no  user  may  write  into  a  directory. 

The  fact  that  a  file  is  a  directory  is  indicated  by  a  bit  in  the  flag  word  of  its  i-node  entry;  see 
/s(5).  The  structure  of  a  directory  entry  as  given  in  the  include  file  is: 

I* 

*  A  directory  consists  of  some  number  of  blocks  of  DIRBLKSIZ 

*  bytes^  where  DIRBLKSIZ  is  chosen  such  that  it  can  be  transferred 

*  to  disk  in  a  single  atomic  operation  (e.g«  512  bytes  on  most  machines). 

* 

*  Each  DIRBLKSIZ  byte  block  contains  some  number  of  directory  entry 

*  structures,  which  are  of  variable  length.  Each  directory  entry  has 

*  a  struct  direct  at  the  front  of  it,  containing  its  inode  number, 

*  the  length  of  the  entry,  and  the  length  of  the  name  contained  in 

*  the  entry.  These  are  followed  by  the  name  padded  to  a  4  byte  boundary 

*  with  null  bytes.  All  names  are  guaranteed  null  terminated. 

The  maximum  length  of  a  name  in  a  directory  is  MAXNAMLEN. 

* 

*  The  macro  DIRSIZ(dp)  gives  the  amount  of  space  required  to  represent 

*  a  directory  entry.  Free  space  in  a  directory  is  represented  by 

*  entries  which  have  dp->d_reclcn  >  DIRSlZ(dp).  All  DIRBLKSIZ  bytes 

*  in  a  directory  block  are  claimed  by  the  directory  entries.  This 

*  usually  results  in  the  last  entry  in  a  directory  having  a  large 

*  dp->d_reclen.  When  entries  are  deleted  from  a  directory,  the 

*  space  is  returned  to  the  previous  entry  in  the  same  directory 

*  block  by  increasing  its  dp->djreclen.  If  the  first  entry  of 
a  directory  block  is  free,  then  its  dp->dJno  is  set  to  0. 

*  Entries  other  than  the  first  in  a  directory  do  not  normally  have 

*  dp->dJno  set  to  0. 

V 

#ifdef  KERNEL 

#define  DIRBLKSIZ  DEVJBSIZE 
#else 

#define  DIRBLKSIZ  512 
#endif 

#define  MAXNAMLEN  255 

/* 

*  The  DIRSIZ  macro  gives  the  minimum  record  length  which  will  hold 
the  directory  entry.  This  requires  the  amount  of  space  in  struct  direct 

*  without  the  d_name  field,  plus  enough  space  for  the  name  with  a  terminating 

*  null  byte  (dp->d_nanilcn+  1),  rounded  up  to  a  4  byte  boundary. 

V 

#undef  DIRSIZ 

#define  DIRSIZ(dp)  ((sizeof  (struct  direct)  -  (MAXNAMLEN-h  1))  +  (((dp)->d_namlen-H  1  +  3jk 
struct  direct  { 
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u_long  d_ino; 

short  d_ieclen; 

short  d_nanilen; 

char  d_name{MAXNAMLEN  +  1); 

/*  typically  shorter  */ 


struct  jdirdesc  { 

int  dd_fd; 

long  ddjoc; 

long  dd_size; 

char  dd  barjDmBLKSIZ]; 

); 

By  convention,  the  first  two  entries  in  each  directory  are  for  and  The  first  is  an  entry  for 
the  directory  itself.  The  second  is  for  the  parent  directory.  The  meaning  of  is  modified  for 
the  root  directory  of  the  master  file  system  (*7”)>  'where  has  the  same  meaning  as 

SEE  ALSO 

f8(5),  readdir(3) 
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NAME 

dump,  dumpdates  -  incremental  dump  format 
SYNOPSIS 

#include  <8y8/type».h> 

#inelude  <8y8/inode.h> 

#lnclude  <dumpre8tor.h> 


DESCRIPTION 

Tapes  used  by  dump  and  re8tore{&)  contain: 


a  header  record 

two  groups  of  bit  map  records 

a  group  of  records  describing  directories 

a  group  of  records  describing  files 

The  format  of  the  header  record  and  of  the  first  record  of  each  description  as  given  in  the  include 
file  <dvmpre8tor.h>  is: 


#define  NTREC 
#define  MLEN 
#defineMSIZ 

#define  TS_TAPE 
#define  TSJNODE 
#deflne  TS.BITS 
#define  TS_ADDR 
#define  TSJEND 
#define  TS_CLRI 
fdeflne  MAGIC 
#deflne  CHECKSUM 

struct  spcl  { 
int 

time_t 

time_t 

int 

daddr_t 

ino_t 

int 

int 

struct 

int 

char 

}  spcl; 

struct  idates  { 
char 
char 


10 

16 

4096 

1 

2 

3 

4 
6 
6 

(int)  60011 
(int)  84446 


c_type; 

c_date; 

c_ddatc; 

c_volume; 

c_tapea; 

cjnumber; 

c_magic; 

c_check8um; 

dinode  c_dinodc; 

c^count; 

c_addr[BSIZE]; 


id_name|16); 

idjncno; 

idjddate; 


}; 


#define  DUMPOUTFMT  ’’%-168  %c  %sr  /*  for  printf  */ 

/*  name,  incno,  ctime(date)  */ 

#define  DUMPINFMT  ”%168  %c  %(^\n]\n”  /♦  inverse  for  scanf  */ 
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NTREC  is  the  default  number  of  1024  byte  records  in  a  physical  tape  block,  changeable  by  the  b 
option  to  dump.  MLEN  is  the  number  of  bits  in  a  bit  map  word.  MSIZ  is  the  number  of  bit  map 
words. 


The  TS_  entries  are  used  in  the  e_type  field  to  indicate  what  sort  of  header  thb  is.  The  types  and 
their  meanings  are  as  follows: 


TS.TAPE 

TSJNODE 

TS3ITS 

TSJIDDR 

TS_EISID 

TS.CLRI 

MAGIC 

CHECKSUM 


Tape  volume  label 

A  file  or  directory  follows.  The  c_dinode  field  is  a  copy  of  the  disk  inode  and  con¬ 
tains  bits  telling  what  sort  of  file  this  is. 

A  bit  map  follows.  This  bit  map  has  a  one  bit  for  each  inode  that  was  dumped. 

A  subrecord  of  a  file  description.  See  e^addr  below. 

End  of  tape  record. 

A  bit  map  follows.  This  bit  map  contains  a  zero  bit  for  all  inodes  that  were  empty 
on  the  file  system  when  dumped. 

All  header  records  have  this  number  in  cjmagic. 

Header  records  checksum  to  this  value. 


The  fields  of  the  header  structure  are  as  follows: 

The  type  of  the  header. 

The  date  the  dump  was  taken. 

The  date  the  file  system  was  dumped  from. 

The  current  volume  number  of  the  dump. 

The  current  number  of  this  (1024-byte)  record. 

The  number  of  the  inode  being  dumped  if  this  is  of  type  TSJNODE. 

This  contains  the  value  MAGIC  above,  truncated  as  needed. 

This  contains  whatever  value  is  needed  to  make  the  record  sum  to  CHECKSUM. 
This  is  a  copy  of  the  inode  as  it  appears  on  the  file  system;  see  /s(5). 

The  count  of  characters  in  c.addr. 

An  array  of  characters  describing  the  blocks  of  the  dumped  file.  A  character  is 
zero  if  the  block  associated  with  that  character  was  not  present  on  the  file  system, 
otherwise  the  character  is  non-zero.  If  the  block  was  not  present  on  the  file  sys¬ 
tem,  no  block  was  dumped;  the  block  will  be  restored  as  a  hole  in  the  file.  If  there 
is  not  sufficient  space  in  this  record  to  describe  all  of  the  blocks  in  a  file, 
TS,.AUDR  records  will  be  scattered  through  the  file,  each  one  picking  up  where  the 
last  left  off. 

Each  volume  except  the  last  ends  with  a  tapemark  (read  as  an  end  of  file).  The  last  volume  ends 
with  a  TS3ND  record  and  then  the  tapemark. 

The  structure  idatet  describes  an  entry  in  the  file  fetcfdumpdateB  where  dump  history  is  kept. 
The  fields  of  the  structure  are: 

id_name  The  dump^  filesystem  is  ‘fievjidjnam’. 

idjncno  The  level  number  of  the  dump  tape;  see  dump{8,). 

id_ddate  The  date  of  the  incremental  dump  in  qrstem  format  see  typee{S). 

FILES 

/ete/dumpdates 
SEE  ALSO 

dttmp(8),  restore(8),  fs(5),  type8(5) 

BUGS 

Should  more  explicitly  describe  format  of  dumpdates  file. 


c_type 

c_date 

cjddate 

c_volume 

cjtapea 

cjnumber 

c_mngic 

cjchecksum 

cjdinode 

cjcount 

c^addr 
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NAME 

environ  -  user  environment 
SYNOPSIS 

extern  char  '*“*envl!ron{ 

DESCRIPTION 

An  array  of  strings  called  the  ‘environment'  is  made  available  by  exeeve{2)  when  a  process  begins. 
By  convention  these  strings  have  the  form  ‘nttme=‘ value’.  The  following  names  are  used  by  vari¬ 
ous  commands: 

PATH  The  sequence  of  directory  prefixes  that  eh,  time,  mVe(l),  etc.,  apply  in  searching  for  a 
file  known  by  an  incomplete  path  name.  The  prefixes  are  separated  by  The 
lojttn(l)  process  sets  PATH=:/u8r/ucb:/bin:/tt8r/bin. 

HOME  A  user’s  login  directory,  set  by  fopn(l)  from  the  password  file  paeewd{5). 

TERM  The  kind  of  terminal  for  which  output  is  to  be  prepared.  This  information  is  used  by 

commands,  such  as  nroffot  p/ot(lG),  which  may  exploit  special  terminal  capabilities. 
See  feteftermeap  {termcap(5))  for  a  list  of  terminal  types. 

SHELL  The  file  name  of  the  user's  login  shell. 

TERMCAP  The  string  describing  the  terminal  in  TERM,  or  the  name  of  the  termcap  file,  see 
termcap(3),termeap{S), 

EXINIT  A  startup  list  of  commands  read  by  ex{l),  edtf(l),  and  tn(l). 

USER  The  login  name  of  the  user. 

Further  names  may  be  placed  in  the  environment  by  the  export  command  and  ‘name=value’ 
arguments  in  sli(l),  or  by  the  eetenv  command  if  you  use  csli(I).  Arguments  may  also  be  placed 
in  the  environment  at  the  point  of  an  execve{2).  It  is  unwise  to  conflict  with  certain  <A(1)  vari¬ 
ables  that  are  frequently  exported  by  ‘.profile’  flies:  MAIL,  PSl,  PS2,  IFS. 

SEE  ALSO 

csb(l),  ex(l),  login(l),  sb(l),  getenv(3),  execve(2),  8ystem(3),  termcap(3X),  termcap(5) 
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NAME 

fcnti  -  file  control  options 


DESCRIPTION 

#include  <fcntLh> 


DESCRffTION 

/cn^/(2)  function  provides  for  control  over  open  files.  This  include  file  describes  requests  and 
arguments  to  fcnti  and  open(2)  as  shown  below: 

/♦  ®(#)fcntl.h  1.2  83/12/08  SMI;  from  UCB  4.2  83/09/25  ♦/ 


/* 

*  Flag  values  accessible  to  open(2)  and  fcntl(2) 

*  (The  first  three  can  only  be  set  by  open) 

*/ 

#defineOJlDONLY  0 
#deflneO_WRONLY  1 
#deflneOJlDWR  2 

#define  0_NDELAY  FNDELAY  /•  Non-blocking  I/O  */ 

#define  O.^APPEND  FAPPEND  /•  append  (writes  guaranteed  at  the  end)  */ 


#ifndefFJDUPFD 
/*  fcntl(2)  requests  */ 
#defineFJ)UPFD  0 

#defineF_GETFD  1 

#defineF_SETFD  2 

#defineF_GETFL  3 

#defineF_SETFL  4 


#defineF_GETOWN  5  /*  Get  owner  */ 
#define  F_SETOWN  6  /*  Set  owner  */ 


/*  Duplicate  fildes  */ 
/*  Get  fildes  flags  */ 
/•  Set  Aides  flags  •/ 
/*  Get  file  flags  */ 

/•  Set  file  flags  */ 


/*  flags  for  F_GETFL,  F_SETFL—  copied  from  <8y8/file.h>  */ 


#define  FNDELAY  00004 

#define  FAPPEND  00010 

#defineFASYNC  00100 

#pndif 


/*  non-blocking  reads  */ 

/*  append  on  each  write  */ 

/*  signal  pgrp  when  data  ready  */ 


SEE  ALSO 

fcntl(2),  open(2) 
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NAME 

fs,  inode  -  format  of  file  system  volume 
SYNOPSIS 

#  Include  <6yfl/type8«h> 

#include  <By8/fllBy8«h> 

^include  <8y8/lnode«h> 

DESCRIPTION 

Every  file  system  storage  volume  (disk,  nine-track  tape,  for  instance)  has  a  common  format  for 
certain  vital  information.  Every  such  volume  is  divided  into  a  certain  number  of  blocks.  The 
block  size  is  a  parameter  of  the  file  system.  Sectors  0  to  15  on  a  file  system  are  used  to  contain 
primary  and  secondary  bootstrapping  programs. 

The  actual  file  system  begins  at  sector  16  with  the  super  block*  The  layout  of  the  super  block  as 
defined  by  the  include  file  <By8ff8.h>  is: 

#defineFS_MAGIC  0x011954 


struct 

fs  *f8jink; 

/*  linked  list  of  file  systems  */ 

struct 

fs  *f8_rlink; 

/*  used  for  incore  super  blocks  */ 

daddr_t  fs^sblkno; 

/*  addr  of  super-block  in  filesys  */ 

daddr_t  fsjcblkno; 

/♦  offset  of  cyl-block  in  filesys  */ 

daddr_t  fs_iblkno; 

/*  offset  of  inode-blocks  in  filesys  */ 

daddr_t  fsjdbikno; 

/*  offset  of  first  data  after  eg  */ 

long 

fsjcgoffsct; 

/*  cylinder  group  offset  in  cylinder  */ 

long 

fs^cgmask; 

/*  used  to  calc  mod  fs_ntrak  */ 

fs^time; 

/*  last  time  written  */ 

long 

fs^size: 

/*  number  of  blocks  in  fs  */ 

long 

fs^dsize; 

/*  number  of  data  blocks  in  fs  */ 

long 

fs^ncg; 

/*  number  of  cylinder  groups  */ 

long 

fs^bsize; 

f*  size  of  basic  blocks  in  fs  */ 

long 

f8_fsize; 

/*  size  of  frag  blocks  in  fs  */ 

long 

fsjrag; 

/*  number  of  frags  in  a  block  in  fs  •/ 

/*  these  are  configuration  parameters 

V 

long 

fs^minfree; 

/*  minimum  percentage  of  free  blocks  */ 

long 

f8_rot  delay; 

/*  num  of  ms  for  optimal  next  block  */ 

long 

fs_rps; 

disk  revolutions  per  second 

/*  these  fields  can  be  computed  from  the  others  */ 

long 

fs_bniask; 

1*  ‘‘blkoff*^  calc  of  blk  offsets  */ 

long 

fsjmask; 

/’•'  *Tragoff*’  calc  of  frag  offsets  */ 

long 

fs^bshift; 

/*  “Iblkno”  calc  of  logical  bikno  */ 

long 

fsjshift; 

/*  *‘numfrag8*^  calc  number  of  frags  */ 

/*  these  are  configuration  parameters 

*1 

long 

fs.maxcontig; 

/*  max  number  of  contiguous  blks  */ 

long 

fs^maxbpg; 

/*  max  number  of  blks  per  cyl  group  */ 

/*  these  fields  can  be  computed  from  the  others  ’•'/ 

long 

fs^fragshift; 

/♦  block  to  frag  shift 

long 

fs^fsbtodb; 

fsbtodb  and  dbtofsb  shift  constant  */ 

long 

fs^sbsize; 

/'•'  actual  size  of  super  block  */ 

long 

f8_c5mask; 

esum  block  offset 

long 

fs^csshift; 

/*  esum  block  number  */ 

long 

fsjindir; 

/*  value  of  NINDIR  ♦/ 

long 

fsjnopb; 

/♦  value  of  INOPB  */ 

long 

fs_nspf; 

/♦  value  of  NSPF  */ 

long 

fs_sparecon[6j; 

f*  reserved  for  future  constants  */ 
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/*  sizes  determined  by  number  of  cylinder  groups  and  their  sizes  */ 

daddr.t  fs^csaddr;  /*  blk  addr  of  cy!  grp  summary  area  */ 

long  fsjcssize;  j*  size  of  cyl  grp  summary  area 

long  fsjcgsize;  /*  cylinder  group  size  */ 

/*  these  fields  should  be  derived  from  the  hardware 


long 

fs.ntrak; 

/*  tracks  per  cylinder  */ 

long 

fsjscct; 

/♦  sectors  per  track  V 

long 

fs_spc; 

/♦  sectors  per  cylinder  */ 

f*  this  comes  from  the  disk  driver  partitioning 

long  fs^ncyl;  j*  cylinders  in  file  ^stem 

f*  these  fields  can  be  computed  from  the  others 


long 

fs-cpg; 

/"•*  cylinders  per  group  */ 

long 

fUpg; 

/*  inodes  per  group  */ 

long 

fsjpg; 

/♦  blocks  per  group  ♦  fsjrag  */ 

this  data  must  be  re-computed  after  crashes  */ 

struct 

esum  fs_cstotal;  /* 

cylinder  summary  information  */ 

these  fields 

are  cleared  at  mount  time 

char 

fs^mod; 

/*  super  block  modified  flag  */ 

char 

fsjclean; 

1*  file  system  is  clean  flag  */ 

char 

f8_ron!y; 

j*  mounted  read-only  flag  */ 

char 

fsjags; 

/♦  currently  unused  flag  */ 

char  fs^fsmntjMAXMNTLENj;  /*  name  mounted  on  */ 
f*  these  fields  retain  the  current  block  allocation  info 

long  fsjcgrptor;  /*  last  eg  searched  */ 

struct  esum  *fs_csp[MAXCSBUFSl;/*  list  of  fs^cs  info  buffers  */ 

long  fsjcpc;  /*  cyl  per  cycle  in  postbl  */ 

short  fsj>oBtbl|MAXCPG][NRPOS];/’*'  head  of  blocks  for  each  rotation  */ 

long  fsjnagic;  /*  magic  number  */ 

ujehar  fs^otbljl];  /•  list  of  blocks  for  each  rotation  */ 

/*  actually  longer  */ 

h 

Each  disk  drive  contains  some  number  of  file  systems.  A  file  system  consists  of  a  number  of 
cylinder  groups.  Each  cylinder  group  has  inodes  and  data. 

A  file  system  is  described  by  its  super*block,  which  in  turn  describes  the  cylinder  groups.  The 
super-block  is  critical  data  and  is  replicated  in  each  cylinder  group  to  protect  against  catastrophic 
loss.  This  is  done  at  file  system  creation  time  and  the  critical  super-block  data  does  not  change, 
so  the  copies  need  not  be  referenced  further  unless  disaster  strikes. 

Addresses  stored  in  inodes  are  capable  of  addressing  fragments  of  ‘block8\  File  system  blocks  of 
at  most  size  MAXBSIZE  can  be  optionally  broken  into  2,  4,  or  S  pieces,  each  of  which  is  address¬ 
able;  these  pieces  may  be  DEV^BSIZE,  or  some  multiple  of  a  DEVJBSIZE  unit. 

Large  files  consist  of  exclusively  large  data  blocks.  To  avoid  undue  wasted  disk  space,  the  last 
data  block  of  a  small  file  is  allocated  as  only  as  many  fragments  of  a  large  block  as  are  necessary. 
The  file  system  format  retains  only  a  single  pointer  to  such  a  fragment,  which  is  a  piece  of  a  sin¬ 
gle  large  block  that  has  been  divided.  The  size  of  such  a  fragment  is  determinable  from  informa¬ 
tion  in  the  inode,  using  the  *^blk8ize(fs,  ip,  Ibn)’’  macro. 

The  file  system  records  space  availability  at  the  fragment  level;  to  determine  block  availability, 
aligned  fragments  are  examined. 

The  root  inode  is  the  root  of  the  file  system.  Inode  0  can't  be  used  for  normal  purposes  and  his¬ 
torically  bad  blocks  were  linked  to  inode  1,  thus  the  root  Inode  is  2  (inode  1  is  no  longer  used  for 
this  purpose,  however  numerous  dump  tapes  make  this  assumption,  so  we  are  stuck  with  it).  The 
lo9t^  found  directory  is  given  the  next  available  inode  when  it  is  initially  created  by  mkfs. 
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fejminfrte  gives  the  minimum  acceptable  percentage  of  file  system  blocks  which  may  be  free.  If 
the  freelist  drops  below  this  level  only  the  super-user  may  continue  to  allocate  blocks.  This  may 
be  set  to  0  if  no  reserve  of  free  blocks  is  deemed  necessary,  however  severe  performance  degrada¬ 
tions  will  be  observed  if  the  file  qrstem  is  run  at  greater  than  90%  full;  thus  the  default  value  of 
fsjmxnfrtt  is  10%. 

Empirically  the  best  trade-off  between  block  fragmentation  and  overall  disk  utilization  at  a  load¬ 
ing  of  90%  comes  with  a  fragmentation  of  4^  thus  the  default  fragment  size  is  a  fourth  of  the 
block  size. 

CylindtT  group  r dated  limita:  Each  cylinder  keeps  track  of  the  availability  of  blocks  at  different 
rotational  positions,  so  that  sequential  blocks  can  be  laid  out  with  minimum  rotational  latency. 
NRPOS  is  the  number  of  rotational  positions  which  are  distinguished.  With  NRPOS  8  the  reso¬ 
lution  of  the  summary  information  is  2ms  for  a  typical  3600  rpm  drive. 

fsjroidtlay  gives  the  minimum  number  of  milliseconds  to  initiate  another  disk  transfer  on  the 
same  cylinder.  It  is  used  in  determining  the  rotationally  optimal  layout  for  disk  blocks  within  a 
file;  the  default  value  for  fsjrotdelay  is  2mB. 

Each  file  system  has  a  statically  allocated  number  of  inodes.  An  inode  is  allocated  for  each  NBPI 
bytes  of  disk  space.  The  inode  allocation  strategy  is  extremely  conservative. 

MAXIPG  bounds  the  number  of  inodes  per  cylinder  group,  and  is  needed  only  to  keep  the  struc¬ 
ture  simpler  by  having  the  only  a  single  variable  size  element  (the  free  bit  map). 

N.B.S  MAXIPG  must  be  a  multiple  of  INOPB(fs). 

MINBSIZE  is  the  smallest  allowable  block  size.  With  a  MINBSIZE  of  4096  it  is  possible  to  create 
files  of  size  2 "32  with  only  two  levels  of  indirection.  MINBSIZE  must  be  big  enough  to  hold  a 
cylinder  group  block,  thus  changes  to  (struct  eg)  must  keep  its  size  within  MIIV^SIZE.  MAXCPG 
is  limited  only  to  dimension  an  array  in  (struct  eg);  it  can  be  made  larger  as  long  as  that 
structure's  size  remains  within  the  bounds  dictated  by  MINBSIZE.  Note  that  super  blocks  are 
never  more  than  size  SBSIZE. 

The  path  name  on  which  the  file  system  is  mounted  is  maintained  in  Js^emni.  MAXMNTLEN 
defines  the  amount  of  space  allocated  in  the  super  block  for  this  name.  The  limit  on  the  amount 
of  summary  information  per  file  system  is  defined  by  MAXCSBUFS.  It  is  currently  parameterized 
for  a  maximum  of  two  million  cylinders. 

Per  cylinder  group  information  is  summarized  in  blocks  allocated  from  the  first  cylinder  group^s 
data  blocks.  These  blocks  are  read  in  from  Je^coaddr  (size  fd  eseize)  in  addition  to  the  super 
block. 

N.B.S  sizeof  (struct  esum)  must  be  a  power  of  two  in  order  for  the  *Ts_cs**  macro  to  work. 

Super  block  for  a  fiie  system:  MAXBPC  bounds  the  size  of  the  rotational  layout  tables  and  is  lim¬ 
ited  by  the  fact  that  the  super  block  is  of  size  SBSIZE.  The  size  of  these  tables  is  Inversely  pro¬ 
portional  to  the  block  size  of  the  file  system.  The  size  of  the  tables  is  increased  when  sector  sizes 
are  not  powers  of  two,  as  this  increases  the  number  of  cylinders  included  before  the  rotational 
pattern  repeats  (  fs^epe).  The  size  of  the  rotational  layout  tables  is  derived  from  the  number  of 
bytes  remaining  in  (struct  fs). 

MAXBPG  bounds  the  number  of  blocks  of  data  pet  cylinder  group,  and  is  limited  by  the  fact  that 
cylinder  groups  are  at  most  one  block.  The  size  of  the  free  block  table  is  derived  from  the  size  of 
blocks  and  the  number  of  remaining  bytes  in  the  cylinder  group  structure  (struct  eg). 

Inode:  The  inode  is  the  focus  of  all  file  activity  in  the  UNIX  file  system.  There  is  a  unique  inode 
allocated  for  each  active  file,  each  current  directory,  each  mounted-on  file,  text  file,  and  the  root. 
An  inode  is  ‘named ^  by  its  device/i-number  pair.  For  further  information,  see  the  include  file 
<^s/inode.h>. 
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NAME 

fstab  -  static  mformation  about  the  file^stems  * 

SYNOPSIS 

#lnelud6  <fBtab.h> 

DESCRIPTION 

The  file  fetcffetab  describes  the  file  systems  and  swapping  partitions  on  the  local  machine.  It  is 
created  by  the  system  administrator  using  a  text  editor  and  processed  by  commands  which 
mount,  unmount,  check  consistency  of,  dump  and  restore  file  systems,  and  by  the  system  in  pro¬ 
viding  swap  space. 

It  consists  of  a  number  of  lines  of  the  form: 

f8_spec:fs_flle:fe_type:fs_freq:f8_pa8sno 
an  example  of  which  would  be: 

/dev/xyOa:/:rw:l:l 


The  entries  from  this  file  are  accessed  using  the  routines  in  getf8ent{3),  which  returns  a  structure 
of  the  following  form; 


struct  fstab  { 
char 
char 
char 
int 
int 


}; 


*f8_8pcc;  /*  block  special  device  name  */ 
♦fs^file;  /*  file  system  path  prefix  */ 
♦fs^type;  /*  rw,ro,sw  or  xx 
fs_frcq;  /*  dump  frequency,  in  days  */ 
fs^passno;  /'*'  pass  number  on  parallel  dump  */ 


The  lines  in  the  file  give  for  each  file  system  or  swap  area  on  the  local  machine  the  disk  partition 
it  is  contained  in  fa^epec  and  the  directory  on  which  it  is  to  be  mounted  (unless  it  is  a  swap  area) 
in  fe^fUe.  The  f8_8pec  special  file  name  is  the  block  special  file  name,  and  not  the  character  spe¬ 
cial  file  name  which  the  rest  of  the  entry  refers  to.  If  a  program  needs  the  character  special  file 
name,  the  program  must  create  it  by  appending  a  **r”  after  the  last  in  the  special  file  name. 


The  fsjype  indicates  whether  it  it  to  be  read-only  "ro”,  readable  and  writable  *‘rw”,  or  readable 
and  writable  subject  to  quotas  “rq”.  It  fa^type  is  “sw”  then  the  special  file  is  made  available  as  a 
piece  of  swap  space  by  the  siy<iport(8)  command  at  the  end  of  the  system  reboot  procedure.  The 
fields  other  than  fa^apae  and  fajtype  are  not  used  in  this  case.  If  fajtype  is  “rq”  then  at  boot  time 
the  file  system  is  automatically  processed  by  the  quoiaehtch(Z)  command  and  disk  quotas  are  then 
enabled  with  ^uo^son(8).  File  system  quotas  are  maintained  in  a  file  * ‘quotas'',  which  is  located 
at  the  root  of  the  associated  file  system.  If  Jajypt  is  specified  as  “xx”  the  entry  is  ignored.  This 
is  useful  to  show  disk  partitions  which  are  currently  not  used. 

The  field  fajrtq  indicates  how  often  each  partition  should  be  dumped  by  the  dump  (8)  command 
(and  triggers  that  commands  w  option  which  tells  which  file  systems  should  be  dumped).  Most 
systems  set  the  fajrtq  field  to  1  indicating  that  the  file  systems  are  dumped  each  day. 

The  final  fielJ  fajpaaano  is  used  by  the  disk  consistency  check  program  fack{S)  to  allow  overapped 
checking  of  file  systems  during  a  reboot.  All  file  systems  with  fa^paaano  of  1  are  first  checked 
simultaneosly,  then  all  file  systems  with  fs_paaano  of  2,  and  so  on.  It  is  usual  to  make  the 
fa^paaano  of  the  root  file  system  have  the  value  1  and  then  check  one  file  system  on  each  available 
disk  drive  in  each  subsequent  pass  to  the  exhaustion  of  file  system  partitions. 

j  tic Jfatah  is  only  read  by  programs,  and  not  written;  it  is  the  duty  of  the  system  administrator  to 
properly  create  and  maintain  this  file.  The  order  of  records  in  Iticjfaiah  is  important  because 
Jack,  mount,  and  umount  process  the  file  sequentially;  file  systems  must  appear  after  file  systems 
they  are  mounted  within. 
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FILES 

/etc/fstab 
SEE  ALSO 

geifseDt(3)^  quotacheck(8),  quotaon(8) 


22 


Last  change:  1$  September  1983 


Sun  Release  1.1 


GETTYTAB(5) 


FILE  FORMATS 


GETTYTAB(5) 


Q 

NAME 

gettytab  -  terminal  configuration  data  base 

SYNOPSIS 

/etc/gettytab 

DESCRIPTION 

Gettyiab  ia  a  simplified  version  of  the  termcap{b)  data  base  used  to  describe  terminal  lines*  The 
initial  terminal  login  process  geHy{S)  accesses  the  geiiytab  file  each  time  it  starts,  allowing  simpler 
reconfiguration  of  terminal  characteristics.  Each  entry  in  the  data  base  is  used  to  describe  one 
class  of  terminals. 

There  is  a  default  terminal  class,  default,  that  is  used  to  set  global  defaults  for  all  other  classes. 

(That  is,  the  default  entry  is  read,  then  the  entry  for  the  class  required  is  used  to  override  particu¬ 

lar  settings.) 

CAPABILITIES 

Refer  to  termcap{b)  for  a  description  of  the  file  layout.  The  default  column  below  lists  defaults 
obtained  if  there  is  no  entry  in  the  table  obtained,  nor  one  in  the  special  default  table. 

Name  Type  Default  Description 
ap  bool  false  terminal  uses  any  parity 

bd  num  0  backspace  delay 

bk  str  0377  alternate  end  of  line  character  (input  break) 

cb  bool  false  use  crt  backspace  mode 

cd  num  0  carriage-return  delay 

ce  bool  false  use  crt  erase  algorithm 

ck  bool  false  use  crt  kill  algorithm 

cl  str  NULL  screen  clear  sequence 

co  bool  false  console  -  add  \n  after  login  prompt 

ds  str  "Y  delayed  suspend  character 

ec  bool  false  leave  echo  OPP 

ep  bool  false  terminal  uses  even  parity 

er  str  "f  erase  character 

et  str  end  of  text  (eof)  character 

ev  str  NULL  initial  enviroment 

fO  num  unused  tty  mode  flags  to  write  messages 

fl  num  unused  tty  mode  flags  to  read  login  name 

f2  num  unused  tty  mode  flags  to  leave  terminal  as 

fd  num  0  form-feed  (vertical  motion)  delay 

fl  str  "O  output  flush  character 
he  bool  false  do  NOT  hangup  line  on  last  close 

he  str  NULL  hostname  editing  string 

hn  str  hostname  hostname 
bt  bool  false  terminal  has  real  tabs 

ig  bool  false  ignore  garbage  characters  in  login  name 

im  str  NULL  initial  (banner)  message 

in  str  ""C  interrupt  character 

is  num  unused  input  speed 

kl  str  "U  kill  character 

Ic  bool  false  terminal  has  lower  case 

Im  str  login:  login  prompt 

In  str  "V  '^literal  next**  character 

lo  str  /bin/login  program  to  exec  when  name  obtained 
nd  num  0  newline  (line-feed)  delay 

nl  bool  false  terminal  has  (or  might  have)  a  newline  character 
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nx 

str 

default  next  table  (for  auto  speed  selection) 

op 

bool 

false 

terminal  uses  odd  parity 

os 

num 

unused  output  speed 

pc 

str 

\0 

pad  character 

pe 

bool 

false 

use  printer  (hard  copy)  erase  algorithm 

Pf 

num 

0 

delay  between  first  prompt  and  followL 

ps 

bool 

false 

line  connected  to  a  MICOM  port  selectt 

qu 

str 

quit  character 

rp 

str 

line  retype  character 

rw 

bool 

false 

do  NOT  use  raw  for  input,  use  ebreak 

sp 

num 

unused  line  speed  (input  and  output) 

su 

str 

z 

suspend  character 

tc 

str 

none 

table  continuation 

tp 

num 

0 

timeout  (seconds) 

tt 

str 

NULL 

terminal  type  (for  enviroment) 

ub 

bool 

false 

do  unbuffered  output  (of  prompts  etc) 

uc 

bool 

false 

terminal  is  known  upper  case  only 

we 

str 

*w 

word  erase  character 

xc 

bool 

fake 

do  NOT  echo  control  chars  as 

xf 

str 

'S 

XOFF  (stop  output)  character 

xn 

str 

‘Q 

XON  (start  output)  character 

If  no  line  speed  is  specified,  speed  wii!  not  be  altered  from  that  which  prevails  when  getty  is 
entered.  Specifying  an  input  or  output  speed  overrides  line  speed  for  stated  direction  only. 

Terminal  modes  to  be  used  for  the  output  of  the  message,  for  input  of  the  login  name,  and  to 
leave  the  terminal  set  as  upon  completion,  are  derived  from  the  Boolean  flags  specifled.  If  the 
derivation  should  prove  inadequate,  any  (or  all)  of  these  three  may  be  overriden  with  one  of  the 
fO,  n,  or  f2  numeric  specifications,  which  can  be  used  to  specify  (usually  in  octal,  with  a  leading 
*0’)  the  exact  values  of  the  flags.  Local  (new  tty)  flags  are  set  in  the  top  16  bits  of  this  (32  bit) 
value. 


Should  geity  receive  a  null  character  (presumed  to  indicate  a  line  break)  it  will  restart  using  the 
table  indicated  by  the  nx  entry.  If  there  is  none,  it  will  re-use  its  original  table. 

Delays  are  specified  in  milliseconds,  the  nearest  possible  delay  available  in  the  tty  driver  will  be 
used.  Should  greater  certainty  be  desired,  delays  with  values  0,  1,  2,  and  3  are  interpreted  as 
choosing  that  particular  delay  algorithm  from  the  driver. 

The  cl  screen  clear  string  may  be  preceded  by  a  (decimal)  number  of  milliseconds  of  delay 
required  (a  la  termcap).  This  delay  is  simulated  by  repeated  use  of  the  pad  character  pc. 

The  initial  message,  and  login  message,  im  and  Im  may  include  the  character  sequence  %h  to 
obtain  the  hostname.  {%%  obtains  a  single  character.)  The  hostname  is  normally  obtained 
from  the  system,  but  may  be  set  by  the  hn  table  entry.  In  either  case  it  may  be  edited  with  he. 
The  he  string  is  a  sequence  of  characters,  each  character  that  is  neither  nor  is  copied  into 
the  final  hostname.  A  in  the  he  string,  causes  one  character  from  the  real  hostname  to  be 
copied  to  the  final  hostname.  A  in  the  he  string,  causes  the  next  character  of  the  real  host- 
name  to  be  skipped.  Surplus  and  characters  are  ignored. 

When  getty  execs  the  login  process,  given  in  the  lo  string  (usually  ” /bin/login”),  it  will  have  set 
the  enviroment  to  include  the  terminal  type,  as  indicated  by  the  tt  string  (if  it  exists).  The  ev 
string,  can  be  used  to  enter  additional  data  into  the  environment.  It  is  a  list  of  comma  separated 
strings,  each  of  which  will  presumably  be  of  the  form  na7ne=value. 

If  a  non-zero  timeout  is  specified,  with  to,  then  getty  will  exit  within  the  indicated  number  of 
seconds,  either  having  received  a  login  name  and  passed  control  to  togin,  or  having  received  an 
alarm  signal,  and  exited.  This  may  be  useful  to  hangup  dial  in  lines. 
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O 

Output  from  getiy  is  even  parity  unless  op  is  specified.  Op  may  be  specified  with  ap  to  allow 
any  parity  on  input,  but  generate  odd  parity  output.  Note:  this  only  applies  while  getty  is  being 
run,  terminal  driver  limitations  prevent  a  more  complete  implementation.  Geliy  does  not  check 
parity  of  input  characters  in  RAW  mode. 

SEE  ALSO 

termcap(5),  getty (8). 


o 
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NAME 

group  -  group  file 
DESCRIPTION 

Group  contains  for  each  group  the  following  information: 

group  name 
encrypted  password 
numerical  group  ID 

a  comma  separated  list  of  all  users  allowed  in  the  group 

This  is  an  ASCII  file.  The  fields  are  separated  by  colons;  Each  group  is  separated  from  the  next 
by  a  new-line.  If  the  password  field  is  nuU»  no  password  is  demanded. 

This  file  resides  in  directory  /etc.  Because  of  the  encrypted  passwords^  it  can  and  does  have  gen¬ 
eral  read  permission  and  can  be  used,  for  example,  to  map  numerical  group  ID’s  to  names. 

FILES 

/etc /group 
SEE  ALSO 

8etgroups(2),  initgroup5(3),  crypt(3)i  pa8swd(l),  pa5swd(5) 

BUGS 

The  passt(;</(l)  command  wonH  change  the  passwords. 


o 
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NAME 

hoets  -  host  name  data  base 
DESCRIPTION 

The  hoets  file  contains  information  regarding  the  known  hosts  on  the  DARPA  Internet.  For  each 
host  a  single  line  should  be  present  with  the  following  information: 

official  host  name 
Internet  address 
aliases 

Items  are  separated  by  any  number  of  blanks  and/or  tab  characters.  A  indicates  the  begin¬ 
ning  of  a  comment;  characters  up  to  the  end  of  the  line  are  not  interpreted  by  routines  which 
search  the  file.  This  file  is  normally  created  from  the  official  host  data  base  maintained  at  the 
Network  Information  Control  Center  (NIC),  though  local  changes  may  be  required  to  bring  it  up 
to  date  regarding  unofficial  aliases  and/or  unknown  hosts. 

Network  addresses  are  specified  in  the  conventional  notation  using  the  routine 

from  the  Internet  address  manipulation  library,  ine^(3N).  Host  names  may  contain  any  printable 
character  other  than  a  field  delimiter,  newline,  or  comment  character. 

FILES 

/etc/hosU 

SEE  ALSO 

getho6tent(3N) 

BUGS 

A  name  server  should  be  used  instead  of  a  static  file.  A  binary  indexed  file  format  should  be 
available  for  fast  access. 
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NAME 

kbd  -  keyboard  translation  table  format  and  default  table 


SYNOPSIS 

fj^Inelude  <Bundev/kbd.h> 


DESCRIPTION 

Keyboard  translation  is  done  in  the  UNIX  kernel  via  a  set  of  tables.  A  translation  table  is  128 
bytes  of  ‘entries’,  which  are  bytes  (unsigned  chars).  The  top  4  bits  of  each  entry  are  decoded  by  a 
case  statement  in  the  keyboard  translator.  If  the  entry  is  less  than  0x80,  it  is  sent  out  as  an  ASCH 
character  (possibly  with  the  META  bit  OR>ed  in).  ‘Special’  entries  are  0x80  or  greater,  and 
invoke  more  complicated  actions. 


struct  keymap  { 

unsigned  char  keymap(l28|: 

}; 


A  keyboard  is  deBned  by  its  keymaps. 


struct  keyboard  { 

struct  keymap 
struct  keymap 
struct  keymap 
struct  keymap 
struct  keymap 
int 
int 

unsigned  char 
unsigned  char 

}; 


*k_normal; 

*k_8hifted; 

*k_cap8; 

*k_controI; 

*k_up; 

k.idleshifts; 

kjdlebuckys; 

k.abortl; 

k_abort2; 


f*  maps  keycodes  to  actions  */ 


/•  Unshifted  */ 

/•  Shifted  ♦/ 

/*  Caps  locked  */ 

/•  Controlled  */ 

/*  Key  went  up  */ 

/*  Shifts  •/ 

/*  Bucky  bits  •/ 

/•  1st  key  of  abort  sequence  */ 
/*  2nd  key  of  abort  sequence  */ 


The  following  defines  the  bit  positions  used  within  k_id!eshifts  to  indicate  the  ‘pressed’  (1)  or 
‘released*  (0)  state  of  shift  keys.  The  bit  numbers  and  the  aggregate  masks  are  defined. 


Since  it  is  possible  to  have  more  than  one  bit  in  the  shift  mask  on  at  once,  there  is  an  implied 
priority  given  to  each  shift  state  when  determining  which  translation  table  to  use.  The  order  is 
(from  highest  priority  to  lowest)  UPMASK,  CIULMASK,  SHIFTMASK,  and  lastly  CAPSMASK. 


#dcflneCAPSLOCK  0 
#defineSHIFTLOCK  1 
#deflneLEFTSHIFT  2 
#defineRIGHTSHIFT  3 
#deflneLEFTCTRL  4 
#defineRIGHTCTRL  5 
#define  CAPSMASK  0x0001 
#define  SHIFTMASK  OxOOOE 
#defineCTRLMASK  0x0030 
#defineUPMASK  0x0080 


/*  Caps  Lock  key  */ 

/*  Shift  Lock  key  */ 

/*  Left-hand  shift  key  */ 

/*  Right-hand  shift  key  */ 

/*  Left-hand  (or  only)  control  key  */ 
/*  Right-hand  control  key  */ 
j*  Caplock  translation  table  */ 
j*  Shifted  translation  table  */ 

/*  Ctrl  shift  translation  table  *f 
f*  Key  up  translation  table  */ 


Special  Entry  Keys 

The  ‘special’  entries’  top  4  bits  are  defined  below.  Generally  they  are  used  with  a  4-bit  parameter 
(such  as  a  bit  number)  in  the  low  4  bits.  The  bytes  whose  top  4  bits  are  0x0  thru  0x7  happen  to 
be  ASCn  characters.  They  are  not  special  cased,  but  just  normal  cased. 


#dcfineSHIFTKEYS  0x80 

thru  0x8F.  This  key  helps  to  determine  the  translation  table  used.  The  bit  position  of 
its  bit  in  ‘shiftmask’  is  added  to  the  entry,  for  example,  SHIFTKEYS+ LEFTCTRL.  When 
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this  entry  is  invoked,  the  bit  in  ‘shiftmask’  is  toggled.  Depending  which  tables  you  put  it 
in,  this  works  well  for  hold-down  keys  or  press-on,  press-off  keys. 

#deiineBUCKYBITS  0x90 

thru  0x9F.  This  key  determines  the  state  of  one  of  the  ‘bucky’  bits  above  the  returned 
ASCn  character.  This  is  basically  a  way  to  pass  mode-key-up/down  information  back  to 
the  caller  with  each  ‘real*  key  depressed.  The  concept,  and  name  ‘bucky’  (derivation 
unknown)  comes  from  the  MIT/SAIL  ‘TV’  system  —  they  had  TOP,  META,  CTRL,  and  a 
few  other  bucky  bits.  The  bit  position  of  its  bit  in  ‘buckybits’,  minus  7,  is  added  to  the 
entry;  for  example,  bit  0x00000400  u  BUdCYBITS-f  3.  The  '-7’  prevents  us  from  messing 
up  the  ASCn  char,  and  gives  us  16  useful  bucky  bits.  When  this  entry  is  invoked,  the 
designated  bit  in  ‘buckybits’  is  toggled.  Depending  which  tables  you  put  it  in,  this  works 
well  for  hold-down  keys  or  press-on,  press-off  keys. 

|deflneMETABlf  0 

Meta  key  depressed  with  key.  This  is  the  only  user  accessible  bucky  bit.  Tbb  value  is 
added  to  BUCKYBITS  in  the  translation  table. 

fdeflneSYSTEMBiT  1 

‘System’  key  was  down  w/key.  This  is  a  kernel-accessible  bucky  bit.  This  value  is  added 
to  BUCKYBITS  in  the  translation  table.  The  system  key  is  currently  not  used  except  as  a 
place  holder  to  indicate  the  key  used  as  the  kjubortl  key  (as  defined  above). 

#deflne  FUNNY  OxAO  /•  thru  OxAF.  This  key  does  one  of  16  funny 

thin^  based  on  the  low  4  bits:  */ 

#deflne  NOP  OxAO  /•  This  key  does  nothing.  •/ 

^define  OOPS  OxAl  /*  This  key  exists  but  is'  undefined.  */ 

#define  HOLE  0xA2  /*  This  key  does  not  exist  on  the  keyboard. 

Its  position  code  should  never  be 
generated.  This  indicates  a  software/ 
hardware  mismatch,  or  bugs.  */ 

#define  NOSCROLL  0xA3  /*  This  key  alternately  sends  'S  or  *Q  */ 

#defineCTRLS  0xA4  /*  This  sends  'S  and  lets  NOSCROLL  know  */ 

#define  CTRLQ  0xA5  /*  This  sends  "Q  and  lets  NOSCROLL  know  */ 

#define  RESET  0xA6  /*  Kbd  was  just  reset  */ 

#define  ERROR  0xA7  /♦  Kbd  just  detected  an  internal  error  */ 

#define  IDLE  OxAS  /*  Kbd  is  idle  (no  keys  down)  */ 

Cdmbihfitions  0xA9  to  OxAF  are  reserved  for  non-parameterized  functions. 

#define  STRING  OxBO 

thru  QxBF.  The  low-order  4  bits  index  a  table  select  a  string  to  be  returned,  char  by 
char.  Each  entry  in  the  table  is  null  terminated. 

#define  KTAB_STRLEN  10  /*  Maximum  string  length  (including  null)  •/ 

Definitions  for  the  individual  string  numbers: 

#defineHOMEARROW  0x00 

#define  UP  ARROW  0x01 

#defineDOWNARROW  0x02 

#d'efineLEFTARROW  0x03 

#defineRIGHTARROW  0x04 
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String  numbers  5  thru  F  are  available  to  users  making  custom  entries. 

Function  Key  Grouptnga 

In  the  following  function  key  groupings,  the  low>order  4  bits  indicate  the  function  key  number 
within  the  group; 

#defincLEFTFUNC  OxCO  /*  thru  OxCF.  The ‘left’ group.  •/ 

#deaneRIGHTFUNO  OxDO  /•  thru  OxDF.  The ‘right’ group.  */ 

#define  TOPFUNC  OxEO  /♦  thru  OxEF.  The ‘top’ group.  */ 

#defineBOTTOMFUNC  OxFO  /*  thru  OxFF.  The ‘bottom’ group.  •/ 

#define  LF(n)  (LEFTFUNC+  (n)-!) 

#define  RF(n)  (RIGHTFUNC+  (n)-l) 

#deflne  TF(n)  (TOPFUNC+  (n)-l) 

^define  BF(n)  (BOTTOMFUNC+  (n)-l) 

The  actual  keyboard  positions  may  not  be  on  the  left/rigbt/top/bottom  of  the  physical  keyboard 
(although  they  usually  are).  What  is  important  is  that  we  have  reserved  64  keys  for  function 
keys. 

Normally,  when  a  function  key  is  pressed,  the  following  escape  sequence  is  sent  through  the  char¬ 
acter  stream: 

ESC[0..9s 

where  ESC  is  a  single  escape  character  and  0..0  indicate  some  number  of  digits  needed  to  encode 
the  function  key  as  a  decimal  number. 

DEFAULT  TABLES 

The  kernel  has  3  sets  of  initial  translation  tables,  one  set  for  each  type  of  keyboard  supported. 
#ifndef  lint 

static  char  8ecsid[]  =  ’’Q(#)keytables.c  1.3  83/10/25  Gopyr  1083  Sun  Micro”; 

#endif 

/* 

*  Copyright  (C)  1983  by  Sun  Microsystems^  Inc. 

V 

/* 

*  keytables.c 

*  This  module  contains  the  translation  tabies  for  the  up-down  encoded 

*  Sun  keyboards. 

V 

#include  "../sun/kbd.h” 

/*  handy  way  to  define  control  characters  in  the  tables  */ 

#define  c(char)  (char&OxlF) 

#define  ESC  Ox  IB 


/*  Unshifted  keyboard  table  for  Micro  Switch  103SD32-2  */ 

static  struct  keymap  keytab_m8_lc  =5  { 

/*  0  */HOLE,  BUCKYBITS+  SYSTEMBIT, 

LF(2),  LF(3),  HOLE,  TF(1),  TF(2),  TF(3), 
/♦  8*/TF(4),  TF(5),  TF(6),  TF(7),  TF(8),  TF(9),  TF(10),  TF(11), 

/*  16  V  TF(12),  TF(13),  TF(l4),c(’(’),  HOLE,  RF(1),  ’+ 
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/*  24*/ 

HOLE,  LF(4), 

’\r, 

LF(6), 

HOLE, 

SHIFTKEYS+  CAPSLC 

’1’. 

’2’, 

/*  32  */ 

’3’,  ’4’, 

’5’, 

’6’, 

’7’, 

-8’, 

’9’, 

’O’, 

/*  40  */ 

1 

HOLE, 

’7’, 

’8’, 

’9’, 

/*  48  */ 

HOLE,  LF(7), 

STRING+  UP  ARROW, 

LF(9), 

y, 

HOLE, 

’\t’, 

y, 

’w’. 

/*56*/ 

’e’,  ’r’. 

’t’, 

’u’. 

’i’, 

’o’. 

’P’, 

/*  64  */ 

9  9 

^  9 

HOLE, 

’4’, 

’5’, 

’6’, 

HOLE, 

/*  72  */ 

STRING+  LEFTARROW, 

/*  80  */ 
/*  88  */ 
/*96*/ 


/*104  */ 
/•112  •/ 
/♦120  ♦/ 


}: 


STRING+  HOMEARROW, 

STRING+  RIGHTARROW, 

HOLE,  SHIFTKEYS+  SHIFTLOCK, 

’a’,  ’s’,  ’d’, 

’r.  ’g’,  ’h’,  ’j’,  ’k’, 

’I’,  ’y,  HOLE,  ’!’,  ’2’,  ’3’,  HOLE,  NOSCROLL, 

STRING+  DOWNARROW, 

LF(©7),  HOLE,  HOLE,  SHIFTKEYS+  LEFTSHIFT, 


’z’, 


’x’. 


’c’. 


m , 


f  t 
f  t 
1  j 


\\  'b*, 

NOP,  0x7F,  NOP, 

HOLE,  HOLE,  SHIFTKEYS+ LEFTCTRL, 

’  SHIFTKEYS+  RIGHTCTRL, 
HOLE,  HOLE,  IDLE, 


7’,  SHIFTKEYS+  RIGHTSHIFT, 
HOLE,  HOLE,  HOLE, 


/*  Shifted  keyboard  table  for  Micro  Switch  103SD32-2  */ 


static  struct  key  map  keytab_m8_uc  —  { 

/♦  0  VHOLE,  BUCJKYBITS+  SYSTEMBIT, 

LF(2),  LF(3),  HOLE,  TF(1),  TF(2),  TF(3), 

/♦  8*/TF(4),  TF(5),  TF(6),  TF(7),  TF(8),  TF(9),  TF(IO),  TF(ll), 

/*  16  ♦/  TF(12),  TF(13),  TF(14),c(*n,  HOLE,  RF(l), 

/*  24  ♦/  HOLE,  LF(4),  ’\r,  LF(6),  HOLE,  SHIFTKEYS+  CAPSLOCK, 

-  f  f 


/•  32  •/ 
/MO*/ 
/•48*/ 

/•  56  •/ 
/•  64  •/ 
/*  72  •/ 


’%’,  ’&’,  ’\”, 

’O’, 

’=’,  ’*’,  ’Q’,  ’\b’,  HOLE, 

HOLE,  LF(7),  STRING+ UP  ARROW, 

’7’, 

’8’. 

’9’, 

LF(9),  HOLE, 

■\t’. 

’Q’, 

’W’, 

’E’,  ’R’,  ’T’,  ’Y’,  ’U’, 

’I’, 

’O’, 

’P’, 

’(’,  ’)’,  'J,  HOLE,  ’4’, 

’5’, 

’6’, 

HOLE, 

STRING+  LEFTARROW, 

STRING+  HOMEARROW, 

STRING+  RIGHTARROW, 

HOLE,  SHIFTKEYS+  SHIFTLOCK, 
’A’,  ’S’,  ’D’, 


/*80*/  ’F’,  ’G’,  ’H’,  ’J’,  ’K’,  ’L’,  ’+’, 

/*  88  •/  ’\V,  ’\r’,  HOLE,  ’2’,  ’3’,  HOLE,  NOSCROLL, 

/•  96  •/  STRING+  DOWNARROW, 

LF(97),  HOLE,  HOLE,  SHIFTKEYS+  LEFTSHIFT, 

’Z’,  ’X’,  ’C’, 

/*104*/  ’V’,  ’B’,  ’N’,  ’M’,  ’<’,  ’>’,  ’?’,  SHIFTKEYS+ RIGHTSHIFT, 

/*112  */  NOP,  OxTF,  ’O’,  NOP,  HOLE,  HOLE,  HOLE, 

/*120  */  HOLE,  HOLE,  SHIFTKEYS+  LEFTCTRL, 
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}: 


SHIFTKEYS+  RIGHTCTRL, 
HOLE,  HOLE,  IDLE, 


/*  Caps  Locked  keyboard  table  for  Micro  Switch  103SD32-2 


’9’, 

'8', 

’Q’, 

■O’, 

’6’, 


’2*, 

’O’, 

'V, 


■W’, 

’P’, 

HOLE, 


static  struct  keymap  keytab_m8_cl  =  { 

/*  0  */H0LE,  BUCKYBITS+  SYSTEMBIT, 

LF(2),  LF(3),  HOLE,  TF(1),  TF(2),  TF(3), 

/*  8*/TF(4),  TF(5),  TF(6),  TF(7),  TF(8),  TF(9),  TF(10),  TF(11), 

/*16*/  TF(12),  TF(13),  TF(14),c(’(’),  HOLE,  RF(1),  ’+ ’, 

HOLE,  LF(4),  ’\r,  LF(6),  HOLE,  SHIFTKEYS+  CAPSLOCK, 

’2’, 

’3’,  ’4’,  ’S’,  ’6’,  ’7’,  ’8’, 

’”,  ’\b’,  HOLE,  ’7’, 

HOLE,  LF(7),  STRING+ UP  ARROW, 

LF(9),  HOLE,  ’\t’, 

’E’,  ’R’,  ’T’,  ’Y’,  ’U’,  T, 

HOLE,  ’4’.  ’S’, 

STRING+  LEFTARROW, 

STRING+  HOMEARROW, 

STRING+  RIGHTARROW, 

HOLE,  SHIFTKEYS+  SHIFTLOCK, 

’A’,  ’S’,  ’D’, 

’F’,  ’G’,  ’H’,  ’J’,  ’K’,  ’L’, 

’I’,  ’\r’,  HOLE,  ’2’,  ’3’,  HOLE,  NOSCROLL, 

STRING+ DOWNARROW, 

LF(97),HOLE,  HOLE,  SHIFTKEYS+ LEFTSHIFT, 

’Z’,  ’X’,  ’C’, 

’V’,  ’B’,  ’N’,  ’M’,  ’,’,  ’/’,  SHIFTKEYS+RIGHTSHIFT, 

NOP,  0x7F,  ’O’,  NOP,  HOLE,  HOLE,  HOLE, 

HOLE,  HOLE,  SHIFTKEYS+  LEFTCTRL, 

”,  SHIFTKEYS+ RIGHTCTRL, 

HOLE,  HOLE,  IDLE, 


I*  24  */ 

j*  32  ♦/ 
/*  40  *! 

I*  48*/ 

/*S0*/ 
/•  64  */ 
/*  72  */ 


/*  80  */ 
/*88*/ 
/*96*/ 


/*104  */ 
/*H2  */ 
/♦120  */ 


}; 


/*  Controlled  keyboard  table  for  Micro  Switch  103SD32-2  */ 

static  struct  keymap  kcytab_m8_ct  =  { 

/*  0  •/HOLE,  BUCKYBITS+  SYSTEMBIT, 

LF(2),  LF(3),  HOLE,  TF(1),  TF(2),  TF(3), 

/•  8*/TF(4),  TF(5),  TF(6),  TF(7),  TF(8),  TF(9),  TF(IO),  TF(ll), 

/•  16  */  TF(12),  TF(13),  TF(14),c(’|’),  HOLE,  RF(1),  OOPS,  OOPS, 

/*  24  */  HOLE,  LF(4),  ’\r,  LF(6),  HOLE,  SHIFTKEYS+  CAPSLOCK, 

OOPS,  OOPS, 

/*  32  ♦/  OOPS,  OOPS,  OOPS,  OOPS,  OOPS,  OOPS,  OOPS,  OOPS, 

/*  40  */  OOPS.  cC"),  c(’®’),  ’\b’,  HOLE,  OOPS,  OOPS,  OOPS, 

/*48*/  HOLE,  LF(7),  STRING+ UP  ARROW, 

LF(9),  HOLE,  ’\t’,  CTRLQ,  c(’W’), 
/*56*/  c(’E’),  c(’R’),  c(’T’),  c(’Y’),  c(’U’),  c(’I’),  c(’O’),  cCP’), 

/*  64  */  c(’(’),  c(’J’),  c(’_’),  HOLE,  OOPS,  OOPS,  OOPS,  HOLE, 

/*  72  •/  STRING+  LEFTARROW, 
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/*  80  •/ 
/*  88  */ 

l*9Q*l 


/*m  */ 
/•112  •/ 
/•120  •/ 


STRING+  HOMEARROW, 

STRING+  RIGHTARROW, 

HOLE,  SHIFTKEYS+  SHIFTLOCK, 

c(’A’),  CTRLS,  c(’D’), 

c(’F’),  c(’G’),  c(’H’),  c(’J’),  c(’K’),  c(’L’),  OOPS,  OOPS, 

c(’\V). 

’\r’,  HOLE,  OOPS,  OOPS,  OOPS,  HOLE,  NOSCROLL, 

STRING+  DOWNARROW, 

LF(97),  HOLE,  HOLE,  SHIFTKEYS+  LEFTSHIFT, 

,  .  ,  ^  ^  c('Z’),  cCX’),  c(’C'). 

c(’V’),  c(’B’),  c(’N’),  c(’M’),  OOPS,  OOPS,  OOPS,  SHIFTKEYS+ RIGHTSHIFT, 

NOP,  0x7F,  OOPS,  NOP,  OOPS,  HOLE,  HOLE,  HOLE, 

HOLE,  HOLE,  SHIFTKEYS+  LEFTCTRL, 

’\0’,  SHIFTKEYS+RIGHTCTRL, 

HOLE,  HOLE,  IDLE, 


/*  "Key  Up”  keyboard  table  for  Micro  Switch  103SD32-2  *f 

static  struct  keymap  keytab_m8_up  =  { 

/♦  OVHOLE,  BUCKYBITS+SYSTEMBIT, 


NOP, 

NOP, 

HOLE,  NOP, 

NOP, 

NOP, 

/*  8VNOP, 

NOP,  NOP, 

NOP, 

NOP, 

NOP,  NOP, 

NOP, 

/*  16  V 

NOP.  NOP, 

NOP, 

NOP, 

HOLE,  NOP, 

NOP, 

NOP, 

/•  24  */ 

HOLE,  NOP, 

NOP, 

NOP, 

HOLE,  SHIFTKEYS+  CAPSLOCK, 

NOP, 

NOP, 

/*  32  V 

NOP,  NOP, 

NOP, 

NOP, 

NOP,  NOP, 

NOP, 

NOP, 

/*  40  */ 

NOP,  NOP, 

NOP, 

NOP, 

HOLE,  NOP, 

NOP, 

NOP, 

/*  48*/ 

HOLE,  NOP, 

NOP, 

NOP, 

HOLE,  NOP, 

NOP, 

NOP, 

/*  58  */ 

NOP,  NOP, 

NOP, 

NOP, 

NOP,  NOP, 

NOP, 

NOP, 

/*  64  */ 

NOP,  NOP, 

NOP, 

HOLE, 

NOP,  NOP, 

NOP, 

HOLE, 

/*  72  */ 

NOP,  NOP, 

NOP, 

HOLE,  SHIFTKEYS+  SHIFTLOCK, 

NOP, 

NOP, 

NOP, 

/•  80  •/ 

NOP,  NOP, 

NOP, 

NOP, 

NOP,  NOP, 

NOP, 

NOP. 

/*  88  */ 

NOP,  NOP, 

HOLE,  NOP, 

NOP,  NOP, 

HOLE,  NOP, 

/*  96  */ 

NOP,  NOP, 

HOLE, 

HOLE, 

SHIFTKEYS+  LEFTSHIFT, 

NOP, 

NOP, 

NOP, 

/•104  */ 

NOP,  NOP, 

NOP, 

NOP, 

NOP,  NOP, 

NOP, 

SHIFTKEYS+  RIGHTSHIFT, 

/*112  */ 

NOP,  NOP, 

NOP, 

NOP, 

NOP,  HOLE, 

HOLE, 

HOLE, 

/*120  V 

HOLE,  HOLE, 

SHIFTKEYS+  LEFTCTRL, 

NOP,  SHIFTKEYS+  RIGHTCTRL, 

HOLE,  HOLE,  RESET, 


/♦  Index  to  keymaps  for  Micro  Switch  103SD32-2  */ 
static  struct  keyboard  keyindex.tns  =  { 
&keytab_ms._Ic, 

&keytab_m8_ijc, 

&keytab_in8_cl, 

&keytab_m8_ct, 

&keytab_m8_up, 
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CTLSMASK, 

/*  Shift  bits  which  stay  on  with  idle  keyboard  7 

0x0000, 

/*  Bucky  bits  which  stay  on  with  idle  keyboard  */ 

1,  77, 

j*  abort  keys  */ 

}; 


/*  Unshifted  keyboard  table  for  Sun>2  keyboard  */ 


static  struct  keytnap  keytab_82_lc  —  { 

/*  0  ‘/HOLE,  BUCKYBITS+  SYSTEMBIT, 

LF(2),  LF(3),  HOLE,  TF(1),  TF(2),  TF(3), 

j*  8*/TF(4),  TF(5),  TF{6),  TF(7),  TF(8),  TF(9),  TF(10),  TF(11), 

/*  16  */  TF(12),  TF(13),  TF(14),  TF(15),  HOLE,  RF(1),  RF(2),  RF(3), 

/*  24  */  HOLE,  LF(4),  LF(5),  LF(6),  HOLE,  c(’l'),  ’1’,  ’2’, 

/*32*/  ’3’,  ’4’,  ’5’,  ’6’,  T,  ’8’,  ’9’,  ’O’, 

i*  40  7  ’=’,  ’”,  ’\b’,  HOLE,  RF(4),  RF(5),  RF(6), 

/*  48  *!  HOLE,  LF(7),  LF(8),  LF(9),  HOLE,  ’\t’,  ’q’,  ’w’, 

58/  e,  r,  t,  y,  u,  i,  o,  p, 

/*64  7  ’{’,  0x7F,  HOLE,  RF(7),  STRING+ UP  ARROW, 

RF(9),  HOLE, 

/t  72  7  LF(IO),  LF(ll),  LF(12),  HOLE,  SHIFTKEYS+  LEFTCTRL, 


/•  80  •/ 
/•  88  •/ 

/•96  7 
/♦104  */ 
/*112  7 
/♦120  */ 


}; 


»  > 


’d’, 

’f’,  ’g’,  ’h’,  'k’l  ’1’,  ’\”, 

’\V,  ’\r’,  HOLE,  STRING+'lEFTARROW, 

RF(ll),  STRING+  RIGHTARROW, 
HOLE,  LF(13), 

LF(14),  LF(15),  HOLE,  SHIFTKEYS+ LEFTSHIFT, 


b ,  n , 


’m’. 


f  t 
t  i 


’x’,  ’c’,  ’v’, 

’/’,  SHIFTKEYS+  RIGHTSHIFT, 

’\n’. 


RF(13),  STRING+  DOWNARROW, 

RF(15),HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 
BUCKYBITS+  METABIT, 

’  ’,  BUCKYBITS+  METABIT, 

HOLE,  HOLE,  HOLE,  ERROR,  IDLE, 


f*  Shifted  keyboard  table  for  Sun-2  keyboard  */ 

static  struct  keymap  keytab_82_uc  =«  { 

/*  0  7HOLE,  BUCKYBITS+ SYSTEMBIT, 

LF(2),  LF(3),  HOLE,  TF(l),  TF(2),  TF(3), 

/*  8  7TF(4),  TF(5),  TF(6),  TF{7),  TF(8),  TF{9).  TF(IO),  TF(n), 

/*  16  */  TF(12),  TF(13),  TF(14),  TF(15),  HOLE,  RF(1),  RF(2),  RF(3), 

/*  24  7  HOLE,  LF(4),  LF{5),  LF(6),  HOLE,  c(’(’),  ’!’, 

/*32  7  ’#’,  ■%’,  ’)’, 

/*40  7  ’J,  ’+’,  ’\b’,  HOLE,  RP(4),  RF(5),  RF(6), 

/*  48  7  HOLE,  LF(7),  LF(8),  LF(9),  HOLE,  ’\t’,  ’Q',  ’W’, 

/*56  7  ’E’,  ’R’,  ’T’,  ’Y’,  ’U’,  ’I’,  ’O’,  ’P’, 

/•64  7  ’{’,  OxTF,  HOLE,  RF(7),  STRING+ UP  ARROW, 

RF(9),  HOLE, 

/*  72  7  LF(iO),  LF(ll),  LF{12),  HOLE,  SHIFTKEYS+  LEFTCTRL, 

’A’  ’S’  ’D’ 

/*80  7  ’F’,  ’G’,  ’H’,  ’J’,  ’K’,  ’L’i 
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/•  88*/ 


/•  96  •/ 
/*104  */ 
/•112  •/ 
/*120  ♦/ 


’I’,  ’\r’,  HOLE,  STRING+LEFTARROW, 

RF(ll),  STRING+  RIGHTARROW, 

HOLE,  LF(13), 

LF(14),  LF(15),  HOLE,  SHIFTKEYS+  LEFTSHIFT, 

’Z’,  ’X’,  ’C’,  ’V’, 

’B’,  ’N’,  ’M’,  SHIFTKEYS+ RIGHTSHIFT, 

’\n’. 

RF(13),  STRING+  DOWNARROW, 

RF(15),HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 
BUCKYBITS+  METABIT, 

’  BUCKYBITS+  METABIT, 

HOLE,  HOLE,  HOLE,  ERROR,  IDLE, 


/*  Controlled  keyboard  table  for  Sun-2  keyboard  */ 

static  struct  keymap  kcytabj52_ct  =  { 

/*  0  */HOLE,  BUCKYBITS+  SYSTEMBIT, 

LF(2),  LF(3),  HOLE,  TF(1),  TF(2),  TF(3), 

/*  8*/TF(4),  TF(5),  TF(6),  TF(7),  TF(8),  TF{9),  TF(IO),  TF(ll), 

/*16*/  TF(12),TF(13),TF(14),TF(15),HOLE,  RF(1),  RF(2),  RF(3), 

/*  24  */  HOLE,  LF(4),  LF(5),  LF(6),  HOLE,  c(’(’), 

/*  32  ♦/  ’3’,  ’4’,  ’6’,  c(’*’),  7’,  ’8’,  ’9’,  ’O’, 

/*  40  •/  c(’_’),  c(’*’),  ’\b’,  HOLE,  RF(4),  RF(5),  RF(6), 

/•  48  */  HOLE,  LF(7),  LF(8),  LF(9),  HOLE,  ’\t’,  c(’q’),  c(’w’), 

/*66*/  c(’e’),  c(’r’),  c(V),  c(-y'),  c(’u’),  c(’i’),  c(-o’),  c(’p’), 

/•64*/  c(’l’),  c(’]’),  0x7F,  HOLE,  RF(7),  STRING+ UP  ARROW, 

RF(9),  HOLE, 

/*  72  •/  LF(IO),  LF(ll),  LF(12),  HOLE,  SHIFTKEYS+  LEFTCTRL, 

c(’a’),  c(’8’),  c(’d’), 

/*80*/  c(’r).  c(’g’),  c(’h’),  c(’j’),  c(’k’),  c(T),  ’\”, 

/•88*/  c(’\V), 

’\r’,  HOLE,  STRING+LEFTARROW, 

RF(ll),  STRING+ RIGHTARROW, 

HOLE,  LF(13), 

/*  96  */  LF(14),  LF(15),  HOLE,  SHIFTKEYS+  LEFTSHIFT, 

/*104*/  c{’b’),  c(’n’),  c(’m’),  ’  c(’J),’  SHIfVkEYS+ RIGHTSHIFT, 

/*112  ♦/  RF(13),  STRING+  DOWNARROW, 

RF(15),  HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 

/*120  •/  BUCKYBITS+  METABIT, 

c(’  ’),  BUCKYBITS+  METABIT, 

HOLE,  HOLE,  HOLE,  ERROR,  IDLE, 


/*  "Key  Up”  keyboard  table  for  Sun-2  keyboard  */ 

static  struct  keymap  keytab_82_up  =  { 

/*  0  */HOLE,  BUCK’i'BITS+  SYSTEMBIT, 
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OOPS,  OOPS,  HOLE,  OOPS,  OOPS,  OOPS, 

/*  8  */OOPS,  OOPS,  OOPS,  OOPS,  OOPS,  OOPS,  OOPS,  OOPS, 

/•  16  •/  OOPS,  OOPS,  OOPS,  OOPS,  HOLE,  OOPS,  OOPS,  NOP, 

/*24*/  HOLE,  OOPS,  OOPS,  OOPS,  HOLE,  NOP,  NOP,  NOP, 

l*32*f  NOP,  NOP,  NOP,  NOP,  NOP,  NOP,  NOP,  NOP, 

/*  40  •/  NOP,  NOP,  NOP,  NOP,  HOLE,  OOPS,  OOPS,  NOP, 

/*  48  •/  HOLE,  OOPS,  OOPS,  OOPS,  HOLE,  NOP,  NOP,  NOP, 

/*  56  •/  NOP,  NOP,  NOP,  NOP,  NOP,  NOP,  NOP,  NOP, 

/♦  64  •/  NOP,  NOP,  NOP,  HOLE,  OOPS,  OOPS,  NOP,  HOLE, 

/*  72  */  OOPS,  OOPS,  OOPS,  HOLE,  SHIFTKEYS+  LEFTCTRL, 

NOP,  NOP,  NOP, 

/*80V  NOP,  NOP,  NOP,  NOP,  NOP,  NOP,  NOP,  NOP, 

/*  88  */  NOP,  NOP,  HOLE,  OOPS,  OOPS,  NOP,  HOLE,  OOPS, 

/♦  96  */  OOPS,  OOPS,  HOLE,  SHIFTKEYS+ LEFTSHIFT, 

NOP,  NOP,  NOP,  NOP, 

/♦104*/  NOP,  NOP,  NOP,  NOP,  NOP,  NOP,  SHIFTKEYS+ RIGHTSHIFT, 

NOP, 

/*112  */  OOPS,  OOPS,  NOP,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 

/*120  */  BUCKYBITS+  METABIT, 

NOP,  BUCKYBITS+ METABIT, 

HOLE,  HOLE,  HOLE,  HOLE,  RESET, 


}; 


/•  Index  to  keymaps  for  Sun-2  keyboard  */ 
static  struct  keyboard  keyiBdexji2  «  { 

&kcytab_82_Ic, 

&keytab_82jic, 

0, 

&kcytab_82_ct, 

&keytab_82_up, 

0x0000,  /*  Shift  bits  which  stay  on  with  idle  keyboard  */ 

0x0000,  /•  Bucky  bits  which  stay  on  with  idle  keyboard  */ 

1,  77,  /•  abort  keys  */ 


/•  Unshifted  keyboard  table  for  "VTIOO  style”  */ 

static  struct  keymap  keytab_vt_lc  =  { 

/•  0*/HOLE,  BUCKYBITS+SYSTEMBIT, 

HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 

/*  8  */HOLE,  HOLE,  STRING+ UP  ARROW, 

STRING+  DOWNARROW, 

STRING+  LEFTARROW, 

STRING+  RIGHTARROW, 


HOLE,  TF(1), 
’3’,  '4', 

r 

16  */ 

TF(2), 

’5’, 

TF(3), 

'6', 

TF(4),  c(’[’), 
'7',  ’8’, 

’2’, 

r 

24  ♦/ 

'9', 

'O', 

I  I  >_I 

/* 

Z2*f 

Ill 

I 

c('H’), 

BUCKYBITS+  METABIT, 

’7’, 

•8’, 

'9', 

’\t’, 

/* 

40  */ 

’q’. 

'w', 

’e',  ’r’. 

’t’. 

y. 

'u',  'i'. 

/* 

48  V 

’o', 

P  » 

■(’.  T. 

0x7F, 

’4’, 

’S’,  ’O’, 

r 

56*/ 

I  f 
f  f 

SHIFTKEYS+  LEFTCTRL, 

SHIFTKEYS+  CAPSLOCK, 
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/•  64  *! 

’h’. 

’j’. 

’k’. 

’a’, 

’1’. 

!*  72  *f 

’2’. 

’3’, 

NOP, 

!*  80  •/ 

’c’, 

’v’, 

’b’. 

n  , 

’s’, 


/♦  88  */ 
1*96*1 

/*m  */ 
1*112  *1 
/*120  •/ 

}; 


I  f 


SHIFTKEYS+  RIGHTSHIFT, 
’\n’,  ’O’,  HOLE. 

HOLE,  HOLE,  ’  ’,  HOLE, 
HOLE,  HOLE,  HOLE,  HOLE, 
HOLE,  HOLE,  HOLE,  HOLE, 
HOLE,  HOLE,  HOLE,  HOLE, 


r,  ’g’, 

’\”.  ’V,  ’W’. 

NOSCROLL, 

SHIFTKEYS+  LEFTSHIFT, 
’z’.  ’x’, 

’m’,  ’/’, 


’\r’,  HOLE,  HOLE, 
HOLE,  HOLE,  HOLE,  HOLE, 
HOLE.  HOLE,  HOLE,  HOLE, 
HOLE,  HOLE,  HOLE,  HOLE, 
HOLE,  HOLE,  HOLE,  IDLE, 


/•  Shifted  keyboard  table  for  "VTIOO  style”  */ 

static  struct  keytnap  keytab_vt_uc  —  { 

/•  0  */HOLE,  BUCKYBITS+  SYSTEMBIT, 

HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 

/•  8*/H0LE,  HOLE,  STRING+ UP  ARROW, 

STRING+  DOWNARROW, 

STRING+  LEFTARROW, 

STRING+ RIGHTARROW, 

/•  16*/ 

/*  24  */ 

/•  32  •/ 

/•  40*/ 

/•  48  •/ 

/*  56  */ 


/*  64  */ 

I*  72  */ 


/•  80  */ 
/*  88  */ 

1*96*1 
/*104  •/ 
/*112  */ 
/•120  •/ 
}; 


HOLE, 

TF(1), 

TF(2), 

TF(3), 

TF(4),  c(’[’), 

^9  9 

‘  9 

’O’, 

» A  » 

9 

9  9 

— .  9 

c(’H’), 

BUCKYBITS+  METABIT, 

’7’, 

’8’, 

’9’, 

9  9 
^  9 

’\t’. 

’Q’. 

’W’, 

’E’,  ’R', 

’T’, 

’Y’, 

V, 

T, 

’O’,  • 

•P’, 

OxTF, 

’4’, 

’S’, 

’6’, 

1  t 

t  9 

SHIFTKEYS+  LEFTCTRL, 

SHIFTKEYS+  CAPSLOCK, 

’A’, 

’S’, 

’D’, 

’F’, 

’G’, 

’H’, 

’J’, 

’K’,  ’L’, 

».» 

’  9 

999  9 

9 

’V’. 

’1’, 

’2’, 

’3’,  NOP, 

NOSCROLL, 

SHIFTKEYS+  LEFTS] 

’Z’. 

’X’, 

’C’, 

’V’, 

’B’,  ’N’, 

’M’, 

•  9 

SHIFTKEYS+  RIGHTSHIFT, 

’\ii’,  ’O’,  HOLE,  ’\r’,  HOLE,  HOLE, 

HOLE,  HOLE.  ’  ’,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 

HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 

HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 

HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  IDLE, 


j*  Caps  Locked  keyboard  table  for  ”VT100  style”  */ 

static  struct  keytnap  keytab_vt_cl  =  { 
j*  0  */HOLE,  BUCKYBITS+  SYSTEMBIT, 

HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 
j*  8*/HOLE,  HOLE,  STRING+ UP  ARROW, 
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r  16  V 

/•  24  V 
/*  32  V 

/*  40  •/ 
/*  48*/ 
/*56*/ 


/•  64  */ 
/*  72  */ 


/*  80  •/ 
/♦  88  •/ 

/*  96  •/ 
/*104  •/ 
/*112  */ 
/*120  •/ 
}: 


STRING+  DOWNARROW, 

STRING+  LEFTARROW, 

STRING+  R IGHTARR  OW, 


HOLE, 

TF(1), 

TF(2),  TF(3), 
’5’,  ’6’, 

TF(4),  c(’(’),  ’1’, 

’7’,  ’8’,  ’9’, 

’2’, 

’3’, 

’4’, 

’O’, 

}  1 
*  > 

1 

c(’H’), 

BUCKYBITS+  METABIT, 

’7’,  ’8’, 

’9’, 

“  J 

’\t’. 

’Q’,  ’W', 

•E’,  ’R’,  ’T’, 

•Y’, 

’U’, 

•r, 

’O’,  ’P’, 

T,  OxTF, 

’4’, 

’6’, 

’6’, 

’,’,  SHIFTKEYS+  LEFTCTRL, 

SHIFTKEYS+  CAPSLOCK, 

’A’,  ’S’. 

•D’, 

’F’, 

’G’, 

’H’,  ’J’, 

’W’. 

’1’,  ’2’, 

’3’,  NOP,  NOSCROLL, 

SHIFTKEYS+  LEFTSHIFT, 
’Z’,  ’X’, 

’C’,  ’V’,  ’B’,  ’N’,  ’M’,  7’, 

SHIFTKEYS+  RIGHTSHIFT, 

’\n’,  ’O’,  HOLE,  ’\r’,  HOLE,  HOLE, 

HOLE,  HOLE,  ’  ’,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 
HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 
HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 
HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  IDLE, 


/*  Controlled  keyboard  table  for  "VTIOO  style”  */ 


static  struct  keymap  keytab_vt_ct  =*  { 

/•  0*/HOLE,  BUCKYBITS+SYSTEMBIT, 

HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 

/*  8  ♦/HOLE,  HOLE,  STR1NG+ UP  ARROW, 

STRING+  DOWNARROW, 

STRING+ LEFTARROW, 

STRING+  RIGHTARROW, 
HOLE,  TF(1), 

/•  16  */  TF(2),  TF(3),  TF(4),  c(’|’),  ’1’,  c(’a’),  ’3’,  ’4’, 

/*24*/  ’5’,  c(’*’),  ’7’,  ’8’,  ’9’,  ’O’,  c(’_’),  ’=’, 

/•32*/  c(’‘’),  c(’H’),  BUCKYBITS+ METABIT, 

’7’,  ’8’,  ’9’,  ’\t’. 


/*  40  */ 
/*  48  */ 
/•  56  */ 


/*  64  */ 
/*  72  */ 


/*80*/ 
/*  88  */ 

/♦  96  ♦/ 


CTRLQ,  c(’W’),  c(’E’),  c(’R’),  c(’T’),  c(’Y’),  c(’U’),  c(’I’), 

c(’O’),  c(’P’),  c(-l’),  c(’l’),  OxTF,  ’4’,  ’5’,  ’6’, 

’,’,  SHIFTKEYS+LEFTCTRL, 

SHIFTKEYS+  CAPSLOCK, 

c(’A’),  CTRLS,  c(’D’),  c{’F’),  c(’G’), 

c(’H’),  c(’J’),  c(’K’),  c(-L’),  ’\r’,  c(’\V), 

’1’,  ’2’i  ’3’,  NOP,  NOSCROLL, 

SHIFTKEYS+  LEFTSHIFT, 
c(’Z’),  c(’X’), 

c(’C’),  c(’V’),  c(’B’),  c(’N’),  c(’M’),  ’,’,  c(’J), 

SHIFTKEYS+  RIGHTSHIFT, 

’\n’,  ’O’,  HOLE,  ’\r’,  HOLE,  HOLE, 

HOLE,  HOLE,  c(’  ’),  HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 
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/*104  */  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 

/•112  */  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 

/*120  */  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  IDLE, 

}: 


/•  "Key  up"  keyboard  table  for  "VTIOO  style”  */ 

static  struct  keymap  keytab_vt_up  =  { 

/•  0  •/HOLE,  BUCKYBITS+  SYSTEMBIT, 

HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 

/•  8  */HOLE,  HOLE,  NOP,  NOP,  NOP,  NOP,  HOLE,  NOP, 

/•  16  •/  NOP,  NOP,  NOP,  NOP,  NOP,  NOP,  NOP,  NOP, 

/•24*/  NOP,  NOP,  NOP,  NOP,  NOP,  NOP,  NOP,  NOP, 

/•32*/  NOP,  NOP,  BUCKYBITS+ METABIT, 

NOP,  NOP,  NOP,  NOP,  NOP, 

/*40*/  NOP,  NOP,  NOP,  NOP,  NOP,  NOP,  NOP,  NOP, 

/♦48*/  NOP,  NOP,  NOP,  NOP,  NOP,  NOP,  NOP,  NOP, 

/*56*/  NOP,  SHIFTKEYS+LEFTCTBL, 

SHIFTKEYS+  CAPSLOCK, 

NOP,  NOP,  NOP,  NOP,  NOP, 

/•64*/  NOP,  NOP,  NOP,  NOP,  NOP,  NOP,  NOP,  NOP, 

/•72*/  NOP,  NOP,  NOP,  NOP,  NOP,  SHIFTKEYS+ LEFTSHIFT, 

NOP,  NOP, 

/*80*/  NOP,  NOP,  NOP,  NOP,  NOP,  NOP,  NOP,  NOP, 

/•  88  •/  SH1FTKEYS+  RIGHTSHIFT, 

NOP,  NOP,  HOLE,  NOP,  NOP,  HOLE,  HOLE, 

/•  96  •/  HOLE,  HOLE,  NOP,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 

/•104  •/  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 

/*112  •/  HOLE.  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE, 

/*120  •/  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  HOLE,  RESET, 

}: 


/•  Index  to  keymaps  for  "VTlOO  style"  keyboard  */ 

static  struct  keyboard  keyindex.vt  =  { 

&keytab_vt_lc, 

&keytab_vtjuc, 

&keytab_vt_cl, 

&keytab_vt_ct, 

&keytab_vt_np, 

CAPSMASK+  CTLSMASK,  /•  Shift  keys  that  stay  on  at  idle  keyboard  •/ 
0x0000,  /*  Bucky  bits  that  stay  on  at  idle  keyboard  */ 

1,  59,  /•  abort  keys  •/ 

}; 

jt^tt***t*t****^*********^***********************^********^*^**^************^ 

/*  Index  table  for  the  whole  shebang 

jt**************************************************************************^ 

int  nkeytables  =  3;  /*  max  16  */ 

struct  keyboard  ♦keytablesj]  =  { 

&keyindex_m8, 

&keyindcx_vt, 
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FILE  FORMATS 


KBD(5) 


&keyindex_s2, 

}: 

/* 

Keyboard  String  Table 

This  defines  the  strings  sent  by  various  keys  (as  selected  in  the 
tables  above), 

•/ 

#definek8te6ciDit(c)  {’\033’,  T,  ’\0’} 
char  key8tringtab(l6|[KTAB_STRLENj  =  { 
kste8cinit(H)  /*home*/, 
k8te6cinit(A)  /*up'^/, 
k8te8cinit(B)  /Mown*/, 
k8te8cinit(D)  /*left*/, 
kstescinitjc)  /*right*/, 

}; 

SEE  ALSO 

con8(4S) 

BUGS 

This  keyboard  translation  implementation  is  essentially  the  PROM  monitor  mechainism  moved 
into  the  kernel.  It  will  almost  certainly  be  reworked  in  the  future  to  take  advantage  of  the 
greater,  flexibility  available  to  the  kernel  that  was  not  available  in  the  PROM, 
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NAME 

mtab  -  mounted  file  system  table 

SYNOPSIS 

#tnclude  <f8tab«h> 

#include  <mtab.h> 

DESCRIPTION 

Mtab  resides  in  directory  fete  and  contains  a  table  of  devices  mounted  by  the  mount  command. 
Umount  removes  entries. 

The  table  is  a  series  of  mtab  structures^  as  defined  in  <mtab.h>.  Each  entry  contains  the  null- 
padded  name  of  the  place  where  the  special  file  is  mounted^  the  null-padded  name  of  the  special 
file,  and  a  type  field,  one  of  those  defined  in  <,fstab.h'> ,  The  special  file  has  all  its  directories 
stripped  away;  that  is,  everything  through  the  last  */*  is  thrown  away.  The  type  field  indicates  if 
the  file  system  is  mounted  read-only,  read-write,  or  read-write  with  disk  quotas  enabled. 

This  table  is  present  only  so  people  can  look  at  it.  It  does  not  matter  to  mount  if  there  are  dupli¬ 
cated  entries  nor  to  umount  if  a  name  cannot  be  found. 

FILES 

/etc/mtab 

SEE  ALSO 

mount(8) 
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NAME 

networks  -  network  name  data  base 
DESCRIPTION 

The  network$  file  contains  information  regarding  the  known  networks  which  comprise  the  DARPA 
Internet.  For  each  network  a  single  line  should  be  present  with  the  following  information: 

official  network  name 
network  number 
aliases 

Items  are  separated  by  any  number  of  blanks  and/or  tab  characters.  A  "#”  indicates  the  begin¬ 
ning  of  a  comment;  characters  up  to  the  end  of  the  line  are  not  interpreted  by  routines  which 
search  the  file.  This  file  is  normally  created  from  the  official  network  data  base  maintained  at  the 
Network  Information  Control  Center  (NIC),  though  local  changes  may  be  required  to  bring  it  up 
to  date  regarding  unofficial  aliases  and/or  unknown  networks. 

Network  number  may  be  specified  in  the  conventional  notation  using  the  inet_network{)  rou¬ 
tine  from  the  Internet  address  manipulation  library,  meI(3N).  Network  names  may  contain  any 
printable  character  other  than  a  field  delimiter,  newline,  or  comment  character. 

FILES 

/etc/networks 

SEE  ALSO 

getnetent(3N) 

BUGS 

A  name  server  should  be  used  instead  of  a  static  file.  A  binary  indexed  file  format  should  be 
available  for  fast  access. 
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NAME 

news  -  USENET  network  news  article,  utility  files 
DESCRIPTION 

There  are  two  formats  of  news  articles:  A  and  B.  A  format  is  the  only  format  that  version  1  net- 
news  systems  can  read  or  write.  Systems  running  the  version  2  netnews  can  read  either  format 
and  there  are  provisions  for  the  version  2  netnews  to  write  in  A  format.  A  format  looks  like  this: 

Aarlicle~ID 

new8group$ 

path 

date 

title 

Bodp  of  article 


Only  version  2  netnews  systems  can  read  and  write  B  format.  B  format  contains  two  extra  pieces 
of  information:  receival  date  and  expiration  date.  The  basic  structure  of  a  B  format  file  consists 
of  a  series  of  headers  and  then  the  body.  A  header  field  is  defined  as  a  line  with  a  capital  letter  in 
the  Ist  column  and  a  colon  somewhere  on  the  line.  Unrecognized  header  fields  are  ignored.  News 
is  stored  in  the  same  format  transmitted,  see  “Standard  for  the  Interchange  of  USENET  Mes¬ 
sages”  for  a  full  description.  The -following  fields  are  among  those  recognized: 

Header  Information 


Promt 

Newsgroups! 

Message-IDi 

Subject! 

Date! 


ueerQhoet.domainf.domain  ...]  (Full  Name) 

Newegrcupe 

<  Unique  Identifier> 

deeeriptive  title 

Date  Potted 


Date-Received! 


Expire!! 

Rep]y-To! 

References! 

Control! 


Date  received  on  local  machine 
Expiration  Date 
Addreee  for  mail  repliet 
Article  ID  of  article  thio  it 
Text  of  a  control  meteage 


Here  is  an  example  of  an  article: 

Relay-Version:  B  2.10  2/13/83  cbosgd.UUCP 

Posting-Version:  B  2.10  2/13/83  eagle.UUCP 
Path:  cbosgdlmhuxjlmhuxtleagleljerry 
From:  jerry Qeagle.uucp  (Jerry  Schwarz) 
Newsgroups:  net.general 
Subject:  Usenet  Etiquette  —  Please  Read 
Message-ID:  <6420easle.UUCP> 

Date:  Friday,  19-Nov.82  16:14:55  EST 
Followup-To:  net.news 
Expires:  Saturday,  l-Jan-83  00:00:00  EST 
Date-Received:  Friday,  19-Nov-82  16:59:30  EST 
Organization:  Bell  Labs,  Murray  Hill 


The  body  of  the  article  comes  here,  after  a  blank  line. 
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NEWS(S) 


A  eye  file  line  has  four  fields,  each  seperated  by  colons: 

8ystem-namt:suh9CTiption$:flags:tr&n$mi88ion  command 

Of  these  fields,  on  the  system-name  and  subscriptions  need  to  be  present. 

The  system  name  is  the  name  of  the  system  being  sent  to.  The  subscriptions  is  the  list  of  news- 
groups  to  be  transmitted  to  the  system.  The  flags  are  a  set  of  letters  describing  how  the  article 
should  be  transmitted.  The  default  is  B.  Valid  flags  include  A  (send  in  A  format),  B  (send  in  B 
format),  N  (use  ihave/sendme  protocol),  U  (use  uux  -c  and  the  name  of  the  stored  article  in  a%8 
string). 

The  trangmiseion  corntnand  is  executed  by  the  shell  with  the  article  to  be  transmitted  as  the  stan¬ 
dard  input.  The  default  is  uux  — s  -r  sysname Irnewi.  Some  examples: 

xy£znet«all 

old8y8met.all|fa«sdl|to«oldsy8iA 

berk8y8mct.all,ucb.all«/u8r/llb/new8/8€ndnew8  -b  berkBy8rnew8 
arpaBy8:net.all>arpa.aUii/u8r/Ub/new8/8endiiew8  -a  rnewiQarpasya 
old2meteaU,faeaUtAi/u8r/lib/8endnewi  -o  oId2rnewB 
u8ertfa.8f-lover8simaU  user 

Somewhere  in  a  eye  file,  there  must  be  a  line  for  the  host  system.  This  line  has  no  Jlag9  or  com- 
mando,  A  #  as  the  first  character  in  a  line  denotes  a  comment. 

The  history,  active,  and  ngflle  files  have  one  line  per  item. 

SEE  ALSO 

inews(l),  po6tnew8(l),  8endnew8(8),  uurcc(8),  readnew8(l) 
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NAME 

newsrc  -  information  file  for  readnews(l)  and  checknews(l) 

DESCRIPTION 

The  ^newsrc  file  contains  the  list  of  previously  read  articles  and  an  optional  options  line  for  read- 
neu;e(l)  and  checknew9(iy  Each  newsgroup  that  articles  have  been  read  from  has  a  line  of  the 
form: 

.IR  newsgroup  :  ”  range” 

Range  is  a  list  of  the  articles  read.  It  is  basically  a  list  of  numbers  separated  by  commas  with 
sequential  numbers  collapsed  with  hyphens.  For  instance: 

genernlf  l-TSfSOfSfi-flO 
fa«lnfo*cpms  1*7 
net.newsi  I 
fa«info-vaxl  ]l«S 

If  the  :  is  replaced  with  an  t  (as  in  tnfo-vax  above)  the  newsgroup  is  not  subscribed  to  and  is  not 
be  shown  to  the  user. 

An  options  line  starts  with  the  word  optloni  (left-justified).  Then  there  are  the  list  of  options 
just  as  they  would  be  on  the  command  line.  For  instance: 
optioM  -n  all  !fa*sf-loverB  lfa«human«iietB  -r 
option! 

A  string  of  lines  beginning  with  a  space  or  tab  after  the  initial  options  line  are  considered  con¬ 
tinuation  lines. 


FILES 

"/.newsrc 
SEE  ALSO 

readnews(l),  checknews(l) 


options  and  list  of  previously  read  articles 
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NAME 

passwd  -  password  file 
DESCRIPTION 

Paeewd  contains  for  each  user  the  following  information: 

name  (login  name,  contains  no  upper  case) 
encrypted  password 
numerical  user  ID 
numerical  group  ID 

user^s  real  name,  office,  extension,  home  phone, 
initial  working  directory 
program  to  use  as  Shell 

The  name  may  contain  meaning  insert  the  login  name. 

The  password  file  is  an  ASCII  file.  Each  field  within  each  user’s  entry  is  separated  from  the  next 
by  a  colon.  Each  user  is  separated  from  the  next  by  a  new-line.  If  the  password  field  is  null,  no 
password  is  demanded;  if  the  Shell  field  is  null,  Ihinfsh  is  used. 

The  password  file  resides  in  directory  /etc.  Because  of  the  encrypted  passwords,  it  can  and  does 
have  general  read  permission  and  can  be  used,  for  example,  to  map  numerical  user  ID’s  to  names. 

Appropriate  precautions  must  be  taken  to  lock  the  file  against  changes  if  it  is  to  be  edited  with  a 
text  editor;  t;$pu;(d)  does  the  necessary  locking. 

FILES 

/etc/passwd 
SEE  ALSO 

getpwent(3),  login(l),  crypt(3),  pa8swd(l),  group(5),  vipw(8),  adduser(8) 

BUGS 

A  binary  indexed  file  format  should  be  available  for  fast  access. 

User  information  (name,  office,  etc.)  should  be  stored  elsewhere. 


46 


Last  change:  13  June  1983 


Sun  Release  1.1 


PHONES  (5) 


FILE  FORMATS 


PHONES  (5) 


NAME 

phones  -  remote  host  phone  number  data  base 
DESCRIPTION 

The  file  /etc/phones  contains  the  system-wide  private  phone  numbers  for  the  ^tp(lC)  program. 
This  file  is  normally  unreadable^  and  so  may  contain  privileged  information.  The  format  of  the 
file  is  a  series  of  lines  of  the  form:  <8ystem-name>[  \tJ*<phone-number>.  The  system  name  is 
one  of  those  defined  in  the  rem<^^e(5)  file  and  the  phone  number  is  constructed  from  [0123456789- 
=*%|.  The  and  characters  are  indicators  to  the  auto  call  units  to  pause  and  wait  for  a 
second  dial  tone  (when  going  through  an  exchange).  The  “5=5”  is  required  by  the  DF02-AC  and 
the  is  required  by  the  BIZCOMP  1030. 

Only  one  phone  number  per  line  is  permitted.  However,  if  more  than  one  line  in  the  file  contains 
the  same  system  name  /ip(lC)  wilt  attempt  to  dial  each  one  in  turn,  until  it  establishes  a  connec¬ 
tion. 

FILES 

/etc/phones 

SEE  ALSO 

tip(lC),  remote(5) 
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NAME 

plot  -  graphics  interface 
DESCRIPTION 

Files  of  this  format  are  produced  by  routines  described  in  p/o/(3X),  and  are  interpreted  for  various 
devices  by  commands  described  in  A  graphics  file  is  a  stream  of  plotting  instructions. 

Each  instruction  consists  of  an  ASCII  letter  usually  followed  by  bytes  of  binary  information.  The 
instructions  are  executed  in  order.  A  point  is  designated  by  four  bytes  representing  the  x  and  y 
values;  each  value  is  a  signed  integer.  The  last  designated  point  in  an  1|  Hi  or  p  instruction 
becomes  the  ^current  point*  for  the  next  instruction. 

Each  of  the  following  descriptions  begins  with  the  name  of  the  corresponding  routine  in  p/o^(3X). 
m  move:  The  next  four  bytes  give  a  new  current  point. 

n  cent:  Draw  a  line  from  the  current  point  to  the  point  given  by  the  next  four  bytes.  See 
plot{lG). 

p  point;  Plot  the  point  given  by  the  next  four  bytes. 

I  line;  Draw  a  line  from  the  point  given  by  the  next  four  bytes  to  the  point  given  by  the  follow¬ 
ing  four  bytes. 

t  label:  Place  the  following  ASCII  string  so  that  its  first  character  falls  on  the  current  point. 
The  string  is  terminated  by  a  newline. 

a  arc:  The  first  four  bytes  give  the  center,  the  next  four  give  the  starting  point,  and  the  last  four 
give  the  end  point  of  a  circular  arc.  The  least  significant  coordinate  of  the  end  point  is  used 
only  to  determine  the  quadrant.  The  arc  is  drawn  counter-clockwise. 

e  circle:  The  first  four  bytes  give  the  center  of  the  circle,  the  next  two  the  radius, 
e  erase:  Start  another  frame  of  output. 

f  linemod:  Take  the  following  string,  up  to  a  newline,  as  the  style  for  drawing  further  lines. 
The  styles  are  ‘dotted,*  ‘solid,*  ‘longdashed,’  ‘shortdashed,’  and  ‘dotdashed.’  Effective  only  in 
plot  4014  and  plot  vtr, 

s  space:  The  next  four  bytes  give  the  lower  left  corner  of  the  plotting  area;  the  following  four 
give  the  upper  right  corner.  The  plot  will  be  magnified  or  reduced  to  fit  the  device  as  closely 
as  possible. 

Space  settings  that  exactly  fill  the  plotting  area  with  unity  scaling  appear  below  for  devices 
supported  by  the  filters  of  piot(lG).  The  upper  limit  is  just  outside  the  plotting  area.  In 
every  case  the  plotting  area  is  taken  to  be  square;  points  outside  may  be  displayable  on  dev¬ 
ices  whose  face  isn^t  square. 

4014  8pace(0,  0,  3120,  3120); 

ver  8pace(0,  0,  2048,  2048); 

300,  300s  space(0,  0,  4096,  4096); 

450  8pace(0,  0,  4096,  4096); 

SEE  ALSQ 

ptot(lG),  plot(3X),  graph(lG) 
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NAME 

prill tcap  -  printer  capability  data  base 

SYNOPSIS 

/etc/printcap 

DESCRIPTION 

Prinicap  is  a  simplified  version  of  the  termcap(b)  data  base  for  describing  printers.  The  spooling 
system  accesses  the  prinicap  file  every  time  it  is  used,  allowing  dynamic  addition  and  deletion  of 
printers.  Each  entry  in  the  data  base  describes  one  printer.  This  data  base  may  not  be  substi¬ 
tuted  for,  as  is  possible  for  term  cap,  because  it  may  allow  accounting  to  be  bypassed. 

The  default  printer  is  normally  /p,  though  the  environment  variable  PRINTER  may  be  used  to 
override  this.  Each  spooling  utility  supports  a  -Ppnntcr  option  to  explicitly  name  a  destination 
printer. 

Refer  to  the  Line  Printer  Spooler  Manual  in  the  Sun  Syetem  Manager's  Manual  tor  a  discussion  of 
how  to  set  up  the  database  for  a  given  printer. 

Each  entry  in  the  prinicap  file  describes  a  printer,  and  is  a  line  consisting  of  a  number  of  fields 
separated  by  characters.  The  first  entry  for  each  printer  gives  the  names  which  are  known  for 
the  printer,  separated  by  characters.  The  first  name  is  conventionally  a  number.  The  second 
name  given  is  the  most  common  abbreviation  for  the  printer,  and  the  last  name  given  should  be  a 
long  name  fully  identifying  the  printer.  The  second  name  should  contain  no  blanks;  the  last 
name  may  well  contain  blanks  for  readability.  Entries  may  continue  onto  multiple  lines  by  giving 
a  \  as  the  last  character  of  a  line,  and  empty  fields  may  be  included  for  readability. 

Capabilities  in  prinicap  are  all  introduced  by  two-character  codes,  and  are  of  three  types: 

Boolean  capabilities  indicate  that  the  printer  has  some  particular  feature.  Boolean  capabilities 
are  simply  written  between  the  characters,  and  are  indicated  by  the  word  'bool*  in 
the  type  column  of  the  capabilities  table  below. 

Numeric  capabilities  supply  information  such  as  baud-rates,  number  of  lines  per  page,  and  so 
on.  Numeric  capabilities  are  indicated  by  the  word  ‘num*  in  the  type  column  of  the 
capabilities  table  below.  Numeric  capabilities  are  given  by  the  two-character  capabil¬ 
ity  code  followed  by  the  character,  followed  by  the  numeric  value.  For  example: 
:br#I200:  is  a  numeric  entry  stating  that  this  printer  should  run  at  1200  baud. 

Siring  capabilities  give  a  sequence  which  can  be  used  to  perform  particular  printer  operations 
such  as  cursor  motion.  String  valued  capabilities  are  indicated  by  the  word  'str'  in  the 
typo  column  of  the  capabilities  table  below.  String  valued  capabilities  are  given  by 
the  twocharacter  capability  code  followed  by  an  sign  and  then  a  string  ending  at 
the  next  following  For  example,  :rp=sspinwriter:  is  a  sample  entry  stating  that 
the  remote  printer  is  named  ^spinwriter’. 

CAPABILITIES 


Name 

Type 

Default 

Description 

af 

sir 

rWLL 

name  of  accounting  file 

br 

num 

none 

if  Ip  is  a  tty,  set  the  baud  rate  (ioctl  call) 

cf 

str 

NULL 

cifplot  data  filter 

df 

str 

NULL 

TeX  data  filter  (DVI  format) 

da 

str 

0 

User  ID  of  user  'daemon". 

fc 

num 

0 

if  Ip  is  a  tty,  clear  flag  bits  (sgtty.h) 

ff 

str 

“\r 

string  to  send  for  a  form  feed 

fo 

bool 

false 

print  a  form  feed  when  device  is  opened 

fs 

num 

0 

like  Tc*  but  set  bits 

gf 

str 

NULL 

graph  data  filter  (plot  (3X)  format) 

ic 

bool 

false 

driver  supports  (non  standard)  ioctl 
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if 

str 

NULL 

call  for  indenting  printout 

name  of  text  filter  which  does  accounting 

If 

str 

“/dev/console* 

error  logging  file  name 

lo 

str 

“lock” 

name  of  lock  file 

Ip 

str 

“/dev/lp” 

device  name  to  open  for  output 

me 

num 

0 

maximum  number  of  copies 

mx 

num 

1000 

maximum  file  size  (in  BUFSIZ  blocks),  zero  unlimited 

nd 

str 

NULL 

next  directory  for  list  of  queues  (unimplemented) 

of 

str 

NULL 

ditroff  data  filter  (device  independent  troff) 

of 

str 

NULL 

name  of  output  filtering  program 

pi 

num 

66 

page  length  (in  lines) 

pw 

num 

132 

page  width  (in  characters) 

px 

num 

0 

page  width  in  pixels  (horizontal) 

py 

num 

0 

page  length  in  pixels  (vertical) 

rf 

str 

NULL 

filter  for  printing  FORTRAN  style  text  files 

rm 

str 

NULL 

machine  name  for  remote  printer 

rp 

str 

”Ip” 

remote  printer  name  argument 

FB 

bool 

false 

restrict  remote  users  to  those  with  local  accounts 

nv 

bool 

false 

open  printer  device  read/write  instead  of  read-only 

sb 

bool 

false 

short  banner  (one  line  only) 

BC 

bool 

false 

suppress  multiple  copies 

sd 

str 

“/usr/spool/lpd" 

spool  directory 

sf 

bool 

false 

suppress  form  feeds 

sh 

bool 

false 

suppress  printing  of  burst  page  header 

st 

str 

“status” 

status  file  name 

tf 

str 

NULL 

troff  data  filter  (cat  phototypesetter) 

tr 

str 

NULL 

trailer  string  to  print  when  queue  empties 

vf 

str 

NULL 

raster  image  filter 

xc 

num 

0 

if  Ip  is  a  tty,  clear  local  mode  bits  (tty  (4)) 

XB 

num 

0 

like  *xc’  but  set  bits 

Error  messages  sent  to  the  console  have  a  carriage  return  and  a  line  feed  appended  to  them, 
rather  than  just  a  line  feed. 

If  the  local  line  printer  driver  supports  indentation,  the  daemon  most  understand  how  to  invoke 
it. 

SEE  ALSO 

termcap(&),  lpc(8),  lpd(8),  pac(8),  Ipr(l),  Ipq(l),  Iprm(l) 

The  Line  Printer  Spooler  Manual  in  the  Sun  System  Manager’s  Manual. 
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c 

NAME 

I>rotocol8  -  protocol  name  data  base 

SYNOPSIS 

/etc/protocols 

DESCRIPTION 

The  protocoh  file  contains  information  regarding  the  known  protocols  used  in  the  DARPA  Inter** 
net.  For  each  protocol  a  single  line  should  be  present  with  the  following  information: 

official  protocol  name 
protocol  number 
aliases 

Items  are  separated  by  any  number  of  blanks  and/or  tab  characters.  A  indicates  the  begin¬ 
ning  of  a  comment;  characters  up  to  the  end  of  the  line  are  not  interpreted  by  routines  which 
search  the  file. 

Protocol  names  may  contain  any  printable  character  other  than  a  field  delimiter^  newline^  or  com¬ 
ment  character. 

EXAMPLE 

The  following  example  is  taken  from  the  Sun  UNIX  ^stem. 


# 

#  Internet  (IP)  protocols 

# 


»p 

0 

IP 

#  internet  protocol,  pseudo  protocol  number 

icmp 

1 

ICMP 

#  internet  control  message  protocol 

sgp 

2 

GGP 

#  gateway-gateway  protocol 

tcp 

6 

TCP 

#  transmission  control  protocol 

pup 

12 

PUP 

#  PARC  universal  packet  protocol 

udp 

17 

UDP 

#  user  datagram  protocol 

FILES 

/ctc/protocols 

SEE  ALSO 

getprotoent(3N) 

BUGS 

A  name  server  should  be  used  instead  of  a  static  file.  A  binary  indexed  file  format  should  be 
available  for  fast  access. 
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NAME 

remote  -  remote  host  description  file 
DESCRIPTION 

The  systems  known  by  ttp(lC)  and  their  attributes  are  stored  in  an  ASCII  file  which  is  structured 
somewhat  like  the  termcap{h)  file.  Each  line  in  the  file  provides  a  description  for  a  single  system. 
Fields  are  separated  by  a  colon  Lines  ending  in  a  \  character  with  an  immediately  follow^ 

Iflg  newline  are  continued  on  the  next  line. 

The  first  entry  is  the  name(8)  of  the  host  system.  If  there  is  more  than  one  name  for  a  system, 
the  names  are  separated  by  vertical  bars.  After  the  name  of  the  system  comes  the  fields  of  the 
description.  A  field  name  followed  by  an  *=’  sign  indicates  a  string  value  follows.  A  field  name 
followed  by  a  '#’  sign  indicates  a  following  numeric  value. 

Entries  named  “tip*”  and  “cu*”  are  used  as  default  entries  by  tip,  and  the  cu  interface  to  tip,  as 
follows.  When  tip  is  invoked  with  only  a  phone  number,  it  looks  for  an  entry  of  the  form 
“tipSOO”,  where  300  is  the  baud  rate  with  which  the  connection  is  to  be  made.  When  the  cu 
interface  is  used,  entries  of  the  form  “cu300”  are  used. 

CAPABILITIES 

Capabilities  are  either  strings  (str),  numbers  (num),  or  boolean  flags  (bool).  A  string  capability  is 
specified  by  capability^value;  e.g.  “dv=/dev/harri8”.  A  numeric  capability  is  specified  by 
cap abilityi^ value-,  e-g*  “xa#99”.  A  boolean  capability  is  specified  by  simply  listing  the  capability. 

at  (str)  Auto  call  unit  type. 

br  (num)  The  baud  rate  used  in  establishing  a  connection  to  the  remote  host.  This  is  a 
decimal  number.  The  default  baud  rate  is  300  baud. 

cm  (str)  An  initial  connection  message  to  be  sent  to  the  remote  host.  For  example,  if  a  host 
is  reached  through  port  selector,  this  might  be  set  to  the  appropriate  sequence  required  to 
switch  to  the  host. 


cu 

dl 

du 

dv 

el 

fn 

hd 

le 

oe 

pa 

pn 

tc 


(str)  Call  unit  if  making  a  phone  call.  Default  is  the  same  as  the  *dv’  field. 

(str)  Disconnect  message  sent  to  the  host  when  a  disconnect  is  requested  by  the  user. 

(bool)  This  host  is  on  a  dial-up  line. 

(str)  UNIX  device(8)  to  open  to  establish  a  connection.  If  this  file  refers  to  a  terminal  line, 
<jp(lC)  attempts  to  perform  an  exclusive  open  on  the  device  to  insure  only  one  user  at  a 
time  has  access  to  the  port. 

(str)  Characters  marking  an  end-oMine.  The  default  is  NULL.  escapes  are  only  recog¬ 
nized  by  tip  after  one  of  the  characters  in  ‘el’,  or  after  a  carriage-return. 

(str)  Frame  size  for  transfers.  The  default  frame  size  is  equal  to  BUFSIZ. 

(bool)  The  host  uses  half-duplex  communication,  local  echo  should  be  performed. 

(str)  Input  end-of-file  marks.  The  default  is  NULL. 

(str)  Output  end-of-file  string.  The  default  is  NULL.  When  tip  is  transferring  a  file,  this 
string  is  sent  at  end-of-file. 


(str)  The  type  of  parity  to  use  when  sending  data  to  the  host.  This  may  be  one  of 
“even”,  “odd”,  “none”,  “zero”  (always  set  bit  8  to  zero),  “one”  (always  set  bit  8  to  1). 
The  default  is  even  parity. 


(str)  Telephone  nuraber(s)  for  this  host.  If  the  telephone  number  field  contains  an  ®  sign, 
tip  searches  the  file  /  etcf  phones  file  for  a  list  of  telephone  numbers;  c.f.  pAones(5). 

(str)  Indicates  that  the  list  of  capabilities  is  continued  in  the  named  description.  This  is 
used  primarily  to  share  common  capability  information. 
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Here  is  a  short  example  showing  the  use  of  the  capability  continuation  feature: 
UNIX-1200:\ 

:dv=/dev/cau0:el=*D*U‘C‘S'Q‘O®:du;at=ventel:ie=#$%:oe=‘D:br#1200: 

arpavax|ax;\ 

:pn=7654321%:tc=UNIX-1200 

PILES 

/etc/remote 

SEE  ALSO 

tip(lC),  phone8(5) 
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NAME 

sccsfile  -  format  of  SCCS  file 
DESCRIPTION 

An  SCCS  file  is  an  ASCII  file.  It  consists  of  six  logical  parts:  the  chtcksum^  the  delta  table  (con¬ 
tains  information  about  each  delta),  user  names  (contains  login  names  and/or  numerical  group 
IDs  of  users  who  may  add  deltas),  flags  (contains  definitions  of  internal  keywords),  comments 
(contains  arbitrary  descriptive  information  about  the  file),  and  the  body  (contains  the  actual  text 
lines  intermixed  with  control  lines). 

Throughout  an  SCCS  file  there  are  lines  which  begin  with  the  ASCII  SOH  (start  of  heading)  char¬ 
acter  (octal  001).  This  character  is  hereafter  referred  to  as  the  control  character  and  will  be 
represented  graphically  as  Q.  Any  line  described  below  which  is  not  depicted  as  beginning  with 
the  control  character  is  prevented  from  beginning  with  the  control  character. 

Entries  of  the  form  DDDDD  represent  a  five  digit  string  (a  number  between  00000  and  00999). 
Each  logical  part  of  an  SCCS  file  is  described  in  detail  below. 

Checksum 

The  checksum  is  the  first  line  of  an  SCCS  file.  The  form  of  the  line  is: 

^hDDDDD 

The  value  of  the  checksum  is  the  sum  of  all  characters,  except  those  of  the  first  line.  The 
®h  provides  a  magic  number  of  (octal)  064001. 

Delta  table 

The  delta  table  consists  of  a  variable  number  of  entries  of  the  form: 

©8  DDDDD/DDDDD/DDDDD 

©d  <type>  <SCCSID>  yr/mo/da  hr:ini:se  <pgmr>  DDDDD  DDDDD 
m  DDDDD  .o 
DDDDD  ••• 

DDDDD  ... 

@m  <MR  number> 


&c  <comments> 


. 

Qe 

The  first  line  (®b)  contains  the  number  of  lines  inserted/deleted/unchanged  respectively. 
The  second  line  (^d)  contains  the  type  of  the  delta  (currently,  normal:  D,  and  removed: 
R),  the  SCCS  ID  of  the  delta,  the  date  and  time  of  creation  of  the  delta,  the  login  name 
corresponding  to  the  real  user  ID  at  the  time  the  delta  was  created,  and  the  serial 
numbers  of  the  delta  and  its  predecessor,  respectively. 

The  @1,  ©X,  and  ©g  lines  contain  the  serial  numbers  of  deltas  included,  excluded,  and 
ignored,  respectively.  These  lines  are  optional. 

The  ©m  lines  (optional)  each  contain  one  MR  number  associated  with  the  delta;  the  ©c 
lines  contain  comments  associated  with  the  delta. 

The  @e  line  ends  the  delta  table  entry. 
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U8tr  namt$ 

The  list  of  login  names  and/or  numerical  group  IDs  of  users  who  may  add  deltas  to  the 
filCi  separated  by  new-llnes.  The  lines  containing  these  login  names  and/or  numerical 
group  IDs  are  surrounded  by  the  bracketing  lines  and  ^U.  An  empty  list  allows  any¬ 
one  to  make  a  delta, 

Flage 

Keywords  used  internally  (see  sdmm(l)  for  more  information  on  their  use).  Each  flag  line 
takes  the  form: 


Of  <flag>  <optionaI  text> 

The  following  flags  are  defined: 

Of  t  <type  of  program> 

Ofy  < program  name> 

Ofi 

Ofb 

Of  m  <module  Dame> 

Off  <floor> 

Of  c  <cciling> 

Of  d  <default-8id  > 

Ofn 

Ofj 

Of  1  <lock-relea5e8> 

Of  q  <u8er  defined  > 


The  t  fiag  defines  the  replacement  for  the  identification  keyword.  The  v  flag  controls 
prompting  for  MR  numbers  in  addition  to  comments;  if  the  optional  text  is  present  it 
defines  an  MR  number  validity  checking  program.  The  i  flag  controls  the  warning/error 
aspect  of  the  “No  id  keywords’*  message.  When  the  I  flag  is  not  present,  this  message  is 
only  a  warning;  when  the  I  flag  is  present,  this  message  will  cause  a  ^Tatal”  error  (the  file 
will  not  be  gotten,  or  the  delta  will  not  be  made).  When  the  b  flag  is  present  the  -b 
keyletter  may  be  used  on  the  gti  command  to  cause  a  branch  in  the  delta  tree.  The  m 
flag  defines  the  first  choice  for  the  replacement  text  of  the  sccsflle.S  identification  key^ 
word.  The  f  flag  defines  the  ^*floor*^  release;  the  release  below  which  no  deltas  may  be 
added.  The  e  flag  defines  the  ^‘ceiling*’  release;  the  release  above  which  no  deltas  may  be 
added.  The  d  flag  defines  the  default  SID  to  be  used  when  none  is  specified  on  a  get  com¬ 
mand.  The  n  flag  causes  dtlia  to  insert  a  ^^null”  delta  (a  delta  that  applies  no  changes) 
in  those  releases  that  are  skipped  when  a  delta  is  made  in  a  new  release  (for  example, 
when  delta  S.l  is  made  after  delta  2.7,  releases  3  and  4  are  skipped).  The  absence  of  the 
n  flag  causes  skipped  releases  to  be  completely  empty.  The  J  flag  causes  get  to  allow  con¬ 
current  edits  of  the  same  base  SID.  The  1  Bag  defines  a  list  of  releases  that  are  locked 
against  editing  (fs^(l)  with  the  keyletter).  The  q  flag  defines  the  replacement  for  the 
%Q%  identification  keyword. 

Commento 

Arbitrary  text  surrounded  by  the  bracketing  tines  and  ^T.  The  comments  section 
typically  will  contain  a  description  of  the  file’s  purpose. 

Body 

The  body  consists  of  text  lines  and  control  lines.  Text  lines  don’t  begin  with  the  control 
character,  control  lines  do.  There  are  three  kinds  of  control  lines:  insert,  delete,  and  end, 
represented  by: 

W DDDDD 
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@D  DDDDD 
dE  DDDDD 

respectively.  The  digit  string  is  the  serial  number  corresponding  to  the  delta  for  the  con¬ 
trol  line. 


SEE  ALSO 

admin(l),  delta(l),  get(l),  prs(l). 

Source  Code  Cottirol  SvoUm  Uoer’o  Guide  by  L.  E.  Bonanni  and  C.  A.  Salemi. 
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NAME 

servers  -  inet  server  data  base 
DESCRIPTION 

The  etrvtra  file  contains  the  list  of  servers  that  tnetd(8)  operates.  For  each  server  a  single  line 
should  be  present  with  the  following  information: 

name  of  server 
protocol 
server  location 

Items  are  separated  by  any  number  of  blanks  and/or  tab  characters.  A  indicates  the  begin¬ 
ning  of  a  comment;  characters  up  to  the  end  of  the  line  are  not  interpreted  by  routines  which 
search  the  file. 

The  name  of  the  server  should  be  the  official  service  name  as  contained  in  aervicea{S).  The  proto¬ 
col  entry  is  either  udp  or  tcp.  The  server  location  is  the  full  path  name  of  the  server  program. 

EXAMPLE 

The  following  example  is  taken  from  the  Sun  UNIX  system. 


tcp 

telnet 

sheU 

login 

exec 

ttcp 

syslog 

coinsat 

talk 

time 

FILES 

/etc/aervers 

SEE  ALSO 


tcp  /usr/etc/in.tcpd 
tcp  /usr/etc/in.telnetd 
tcp  /etc/in.rshd 
tcp  /etc/in.tlogind 
tcp  /usr/etc/in.rexecd 
udp  /u6r/ete/in.ttcpd 
udp  /usr/etc/in.^slog 
udp  /u8r/etc/in.comsat 
udp  /usr/etc/in.talkd 
tcp  /usr/etc/in.timed 


serviees(5),  inetd(8) 
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NAME 

services  -  service  name  data  base 

SYNOPSIS 

/ete/servlees 

DESCRIPTION 

The  services  file  contains  information  regarding  the  known  services  available  in  the  DARPA  Inter¬ 
net.  For  each  service  a  single  line  should  be  present  with  the  following  information: 

official  service  name 
port  number 
protocol  name 
aliases 

Items  are  separated  by  any  number  of  blanks  and/or  tab  characters.  The  port  number  and  proto¬ 
col  name  are  considered  a  single  item;  a  is  used  to  separate  the  port  and  protocol  (for 
instance,  “512/tcp”).  A  indicates  the  beginning  of  a  comment;  characters  up  to  the  end  of 
the  line  are  not  interpreted  by  routines  which  search  the  file. 

Service  names  may  contain  any  printable  character  other  than  a  field  delimiter,  newline,  or  com¬ 
ment  character. 

EXAMPLE 

Here  is  an  example  of  the  f  etef  services  file  from  the  Sun  UNIX  System. 

# 

#  Network  services,  Internet  style 

# 


echo 

7/udp 

discard 

9/ttdp 

sink  null 

systat 

11/tcp 

daytime 

13/tcp 

netstat 

15/tcp 

ftp 

21/tcp 

telnet 

23/tcp 

smtp 

25/tep 

mail 

time 

37/tcp 

timserver 

name 

42/tcp 

nameserver 

M^hois 

43/tcp 

mtp 

# 

#  Host  specific  functions 

# 

57/tcp 

#  deprecated 

tftp 

69/udp 

rie 

77/tcp 

finger 

79/tcp 

link 

87/tcp 

ttylink 

supdup 

# 

#  UNIX  specific  services 

# 

95/tcp 

exec 

512/tcp 

login 

513/tcp 

shell 

514/tcp 

cmd 

efs 

520/tcp 

biff 

512/udp 

comsat 

who 

513/udp 

whod 
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syslog  514/udp 

talk  517/udp 

route  520/adp  router  routed#  521  also 

FILES 

/etc/services 

SEE  ALSO 

get5ervent(3N) 

BUGS 

A  same  server  should  be  used  instead  of  a  static  file,  A  binary  indexed  file  format  should  be 
available  for  fast  access. 
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NAME 

tar  -  tap«  archive  file  format 
DESCRIPTION 

Tar,  (the  tape  archive  command)  dumps  several  files  into  one,  in  a  medium  suitable  for  transpor¬ 
tation. 

A  “tar  tape”  or  file  is  a  series  of  blocks.  Each  block  is  of  size  TBLOCK.  A  file  on  the  tape  is 
represented  by  a  header  block  which  describes  the  file,  followed  by  zero  or  more  blocks  which  give 
the  contents  of  the  file.  At  the  end  of  the  tape  are  two  blocks  filled  with  binary  zeros,  as  an  end- 
of-file  indicator. 

The  blocks  are  grouped  for  physical  I/O  operations.  Each  group  of  n  blocks  (where  n  is  set  by 
the  b  keyletter  on  the  lur(l)  command  line  —  default  is  20  blocks)  is  written  with  a  single  system 
call;  on  nine-track  tapes,  the  result  of  this  write  is  a  single  tape  record.  The  last  group  is  always 
written  at  the  full  size,  so  blocks  after  the  two  zero  blocks  contain  random  data.  On  reading,  the 
specified  or  default  group  size  is  used  for  the  first  read,  but  if  that  read  returns  less  than  a  full 
tape  block,  the  reduced  block  size  is  used  for  further  reads,  unless  the  B  keyletter  is  used. 

The  header  block  looks  like: 

#deflne  TBLOCK  &12 

#define  NAMSIZ  100 

union  hblock  { 

char  dummy  [TBLOCK]; 
struct  header  { 

char  namejNAMSIZj; 

char  modejsj; 

char  uid[8|; 

char  gid[8]; 

char  sizejlQ]; 

char  mtime|l2]; 

char  chksum[8]; 

char  linkflag; 

char  !inkname|NAMSIZ|; 

)  dbuf; 

}; 

Name  is  a  nuU-terminated  string.  The  other  fields  are  zero-filled  octal  numbers  in  ASCII.  Each 
field  (of  width  w)  contains  w-2  digits^  a  space,  and  a  null,  except  size  and  which  do  not 

contain  the  trailing  null.  Name  is  the  name  of  the  file,  as  specified  on  the  tar  command  line. 
Files  dumped  because  they  were  in  a  directory  which  was  named  in  the  command  line  have  the 
directory  name  as  prefix  and  j filename  as  suffix.  Mode  is  the  file  mode,  with  the  top  bit  masked 
off.  Uid  and  gid  are  the  user  and  group  numbers  which  own  the  file.  Size  is  the  size  of  the  file  in 
bytes.  Links  and  symbolic  links  are  dumped  with  this  field  specified  as  zero.  Mtime  is  the 
modification  time  of  the  file  at  the  time  it  was  dumped.  Chkeum  is  a  decimal  ASCII  value  which 
represents  the  sum  of  all  the  bytes  in  the  header  block.  When  calculating  the  checksum,  the 
ckksum  field  is  treated  as  if  it  were  all  blanks.  Linkflag  is  ASCII  *0^  if  the  file  is  “normal*’  or  a 
special  file,  ASCII  *1’  if  it  is  an  hard  link,  and  ASCII  *2*  if  it  is  a  symbolic  link.  The  name 
linked-to,  if  any,  is  in  linkname,  with  a  trailing  null.  Unused  fields  of  the  header  are  binary  zeros 
(and  are  included  in  the  checksum). 

The  first  time  a  given  i-node  number  is  dumped,  it  is  dumped  as  a  regular  file.  The  second  and 
subsequent  times,  it  is  dumped  as  a  link  instead.  Upon  retrieval,  if  a  link  entry  is  retrieved,  but 
not  the  file  it  was  linked  to,  an  error  message  is  printed  and  the  tape  must  be  manually  re¬ 
scanned  to  retrieve  the  iinked-to  file. 
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The  encoding  of  the  header  is  designed  to  be  portable  across  machines. 

SEE  ALSO 
tar(l) 

BUGS 

Names  or  linknames  longer  than  NAMSIZ  produce  error  reports  and  cannot  be  dumped. 
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NAME 

term  -  terminal  driving  tables  for  nroff 
DESCRIPTION 

iVro^l)  uses  driving  tables  to  customize  its  output  for  various  types  of  output  devices,  such  as 
printing  terminals,  special  word-processing  terminals  (such  as  Diablo,  Qume,  or  NEC  Spinwriter 
mechanisms),  or  special  output  filter  programs.  These  driving  tables  are  written  as  0  programs, 
compiled,  and  installed  in  /usr/Ub/term/tabnume  f  where  name  is  the  name  for  that  terminal 
type  as  given  in  term{7). 

Here’s  how  to  construct  a  driver  table  for  USG  UNIX  "nroff*,  in  25  easy  lessons.  The  only 
changes  for  the  V7  nroff  (on  4.xBSD  as  well)  are  that  the  ”iton*  and  *itofr  entries  are  missing, 
the  "bset*  and  "breset”  entries  affect  the  "s&^ags*  word  in  the  "sgtty*  structure,  and  the  pro¬ 
cedures  for  making  the  table  are  different. 

Special  thanks  to  the  people  at  AT&T  responsible  for  the  UNIX  documentation,  without  whose 
help  this  posting  would  not  have  been  necessary.  The  structure  of  the  tables  is  as  follows: 

#define  INCH  240 
struct  { 

int  bset; 
int  breset; 
int  Hor; 
int  Vert; 
int  Newline; 
int  Char; 
int  Em; 
int  Halfline; 
int  Adj; 
char  *twinit; 
char  *twrest; 
char  *twnl; 
char  *hlr; 
char  *hlf; 
char  *flr; 
char  *bdon; 
char  *bdoff; 
char  *iton; 
char  *itoff; 
char  *ploton; 
char  *plotoff; 
char  *up; 
char  *down; 
char  •right; 
char  *1611; 

char  •codetab(256-32); 
char  ^izz; 

The  meanings  of  the  various  fields  are  as  follows: 

beet  bits  to  set  in  the  c^ofiag  field  of  the  termio  structure  (see  fty(4))  before  output. 

breaet  bits  to  reset  in  the  c_ofiag  field  of  the  (ermto  structure  before  output. 

Hor  horizontal  resolution  in  fractions  of  an  inch. 

Vert  vertical  resolution  in  fractions  of  an  inch. 
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Newline 

Chur 

Em 

Halfline 

Adj 

twinit 

twreet 

Iwt^ 

klr 

hi! 

fir 

hicn 

hdoff 

iton 

itoff 

ploton 

ptoioff 

up 

down 

right 

left 

codetob 


space  moved  by  a  newline  (linefeed)  character  in  fractions  of  an  inch. 

quantum  of  character  sizes^  in  fractions  of  an  inch,  (that  is,  a  character  is  a  multiple 
of  Char  units  wide) 

size  of  an  em  in  fractions  of  an  inch* 

space  moved  by  a  half-linefeed  (or  half-reverse-linefeed)  character  in  fractions  of  an 
inch. 

quantum  of  white  space,  in  fractions  6f  an  inch,  (that  is,  white  spaces  are  a  multiple 
of  Adj  units  wide) 

Note:  if  this  is  less  than  the  size  of  the  space  character  (in  units  of  Char;  see  below  for 
how  the  sizes  of  characters  are  defined),  nroff  will  output  fractional  spaces  using  plot 
mode.  Also,  if  the  -e  switch  to  nroff  used,  Adj  is  set  equal  to  Her  by  nroff. 

set  of  characters  used  to  initialize  the  terminal  in  a  mode  suitable  for  nroff. 

set  of  characters  used  to  restore  the  terminal  to  normal  mode. 

set  of  characters  used  to  move  down  one  line. 

set  of  characters  used  to  move  up  one-half  line. 

set  of  characters  used  to  move  down  one-half  line. 

set  of  characters  used  to  move  up  one  line. 

set  of  characters  used  to  turn  on  hardware  boldface  mode,  if  any. 

set  of  characters  used  to  turn  off  hardware  boldface  mode,  if  any. 

set  of  characters  used  to  turn  on  hardware  italics  mode,  if  any. 

set  of  characters  used  to  turn  off  hardware  italics  mode,  if  any. 

set  of  characters  used  to  turn  on  hardware  plot  mode  (for  Diablo  type  mechanisms),  if 
any. 

set  of  characters  used  to  turn  off  hardware  plot  mode  (for  Diablo  type  mechanisms),  if 
any. 

set  of  characters  used  to  move  up  one  resolution  unit  (Vert)  in  plot  mode,  if  any. 
set  of  characters  used  to  move  down  one  resolution  unit  (Vert)  in  plot  mode,  if  any. 

set  of  characters  used  to  move  right  one  resolution  unit  (Hor)  in  plot  mode,  if  any. 

set  of  characters  used  to  move  left  one  resolution  unit  (Hor)  in  plot  mode,  if  any. 

definition  of  characters  needed  to  print  an  nroff  character  on  the  terminal.  The  first 
byte  is  the  number  of  character  units  (Char)  needed  to  hold  the  character;  that  is, 
**\001^*  is  one  unit  wide,  **\002'’  is  two  units  wide,  etc.  The  high-order  bit  (0200)  is 
on  if  the  character  is  to  be  underlined  in  underline  mode  (.ul).  The  rest  of  the  bytes 
are  the  characters  used  to  produce  the  character  in  question.  If  the  character  has  the 
sign  (0200)  bit  on,  it  is  a  code  to  move  the  terminal  in  plot  mode.  It  is  encoded  as: 

0100  bit  on.  ^  vertical  motion. 

0100  bit  off  horizontal  motion. 

040  bit  on  negative  (up  or  left)  motion. 

040  bit  off  positive  (down  or  right)  motion. 

037  bits  number  of  such  motions  to  make, 

a  zero  terminator  at  the  end. 
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All  quantities  which  »e  in  units  of  fractions  of  an  Inch  should  be  expressed  as 
INCH*num/(fenom,  where  num  and  denom  are  respectively  the  numerator  and  denominator  of 
the  fraction;  that  is,  1/48  of  an  inch  would  be  written  as  “INCH/48”. 

If  any  sequence  of  characters  does  not  pertain  to  the  output  device,  that  sequence  should  be  given 
as  a  null  string. 

The  source  code  for  the  terminal  name  is  in  /usr/Bre/emd/text/roff.d/terinn.d/tabname.e. 
When  a  new  terminal  type  is  added,  the  file  makeiermt.c  should  be  updated  to  ‘^include’  the 
source  to  that  driving  table;  note  that  the  various  terminal  types  are  grouped  into  “parts” 
labelled  PARTI,  PART2,  and  PART3.  If  necessary,  more  parts  can  be  added.  Other  changes 
necessary  to  maktterm».c  are  left  as  an  exercise  to  the  reader.  The  makefile  tertM.mk  in  that 
directory  should  then  be  updated. 

FILES 

/usr/lib/term/tabnam$  driving  tables 
tabnams.c  source  for  driving  tables 

SEE  ALSO 

troff(l),  term(7) 
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NAME 

termcs4>  -  terminal  capability  data  base 

SYNOPSIS 

/etc/termcap 

DESOMPTION 

Ttrmcap  u  a  data  base  describing  terminals,  used,  for  example,  by  w(l)  and  c«r9es(3X).  Termi¬ 
nals  are  described  in  ttrmeap  by  giving  a  set  of  capabilities  which  they  have,  and  by  describing 
how  operations  are  performed.  Padding  requirements  and  initialization  sequences  are  included  in 
ttrmcap. 

Each  entry  in  the  ttrmcap  file  describes  a  terminal,  and  is  a  line  consisting  of  a  number  of  fields 
separated  by  characters.  The  first  entry  for  each  terminal  gives  the  names  which  are  known 
for  the  terminal,  separated  by  ‘|’  characters.  The  first  name  is  always  2  characters  long  and  is 
used  by  older  version  6  systems  which  store  the  terminal  type  in  a  16  bit  word  in  a  systemwide 
data  base.  The  second  name  given  is  the  most  common  abbreviation  for  the  terminal,  and  the 
last  name  given  should  be  a  long  name  fully  identifying  the  terminal.  The  second  name  should 
contain  no  blanks;  the  last  name  may  well  contain  blanks  for  readability.  Entries  may  continue 
onto  multiple  lines  by  giving  a  \  as  the  last  character  of  a  line,  and  empty  fields  may  be  included 
for  readability. 

Capabilities  in  ttrmcap  are  all  introduced  by  two-character  codes,  and  are  of  three  types: 

Boolean  capabilities  indicate  that  the  terminal  has  some  particular  feature.  Boolean  capabili¬ 
ties  are  simply  written  between  the  characters,  and  are  indicated  by  the  word  ‘bool’ 
in  the  type  column  of  the  capabilities  table  below. 

Numeric  capabilities  supply  information  such  as  the  size  of  the  terminal  or  the  size  of  particular 
delays.  Numeric  capabilities  are  indicated  by  the  word  ‘num’  in  the  type  column  of 
the  capabilities  table  below.  Numeric  capabilities  are  given  by  the  two-character 
capability  code  followed  by  the  '#’  character  and  then  the  numeric  value.  For  exam¬ 
ple:  :eo#80:  is  a  numeric  entry  stating  that  this  terminal  has  $0  columns. 

String  capabilities  give  a  sequence  which  can  be  used  to  perform  particular  terminal  operar 
tions  such  as  cursor  motion.  String  valued  capabilities  are  indicated  by  the  word  ‘str’ 
in  the  type  column  of  the  capabilities  table  below.  String  valued  capabilities  are 
given  by  the  two-character  capability  code  followed  by  an  *=’  sign  and  then  a  string 
ending  at  the  next  following  For  example,  :ce=16\E*S:  is  a  sample  entry  for 
clear  to  end-of-line. 

CAPABILITIES 


(P) 

indicates  padding  may  lie  specified 

(P*) 

indicates  that  padding  may  be  based  on  the  number  of  lines  affected 

NumeType  Pnd? 

Description 

ae 

str 

(P) 

End  alternate  character  set 

al 

str 

(P*) 

Add  new  blank  line 

am 

bool 

Terminal  has  automatic  margins 

as 

str 

(P) 

Start  alternate  character  set 

be 

str 

Backspace  if  not  "'ll 

bs 

bool 

Terminal  can  backspace  with 

bt 

str 

(P) 

Back  tab 

bw 

bool 

Backspace  wraps  from  column  0  to  last  column 

CC 

str 

Command  character  in  prototype  if  terminal  settable 

cd 

str 

(P*) 

Clear  to  end  of  display 

CC 

str 

(P) 

Clear  to  end  of  line 

ch 

str 

(P) 

Like  cm  but  horizontal  motion  only,  line  stays  same 

cl 

str 

(P*) 

Clear  screen 

cm 

str 

(P) 

Cursor  motion 
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CO 

num 

Number  of  columns  in  a  line 

cr 

str 

(p*) 

Carriage  return,  (default  *M) 

C8 

8tr 

(p) 

Change  scrolling  region  (vtlOO),  like  cm 

cv 

str 

(p) 

Like  ch  but  vertical  only. 

da 

bool 

Display  may  be  retained  above 

dB 

num 

Number  of  millisec  of  bs  delay  needed 

db 

bool 

Display  may  be  retained  below 

dC 

num 

Number  of  millisec  of  cr  delay  needed 

dc 

str 

(p*) 

Delete  character 

dF 

num 

Number  of  millisec  of  ff  delay  needed 

dl 

str 

(p*) 

Delete  line 

dm 

str 

Delete  mode  (enter) 

dN 

num 

Number  of  millisec  of  nl  delay  needed 

do 

str 

Down  one  line 

dT 

num 

Number  of  millisec  of  tab  delay  needed 

ed 

str 

End  delete  mode 

ei 

8tr 

End  insert  mode;  give  “:ei=:”  if  le 

eo 

str 

Can  erase  overstrikes  with  a  blank 

ff 

str 

(p*) 

Hardcopy  terminal  page  eject  (default  ‘L) 

he 

bool 

Hardcopy  terminal 

bd 

str 

Half-line  down  (forward  1/2  linefeed) 

bo 

str 

Home  cursor  (if  no  cm) 

bu 

str 

Half-line  up  (reverse  1/2  linefeed) 

Hazeltine;  can’t  print  "’s 

bz 

str 

ic 

str 

(p) 

Insert  character 

if 

str 

Name  of  file  containing  In 

im 

bool 

Insert  mode  (enter);  give  “:ims=:”  if  ie 

in 

bool 

Insert  mode  distinguishes  nulls  on  display 

ip 

str 

(p*) 

Insert  pad  after  character  inserted 

is 

str 

Terminal  initialization  string 

k0*k9 

str 

Sent  by  “other”  function  keys  0-9 

kb 

str 

Sent  by  backspace  key 

kd 

str 

Sent  by  terminal  down  arrow  key 

ke 

str 

Out  of  “keypad  transmit”  mode 

kb 

str 

Sent  by  home  key 

kl 

str 

Sent  by  terminal  left  mow  key 

kn 

num 

Number  of  “other”  keys 

ko 

str 

Termcap  entries  for  other  non-function  keys 

kr 

str 

Sent  by  terminal  right  arrow  key 

ks 

str 

Put  terminal  in  “keypad  transmit”  mode 

ku 

str 

Sent  by  terminal  up  arrow  key 

10-19 

str 

Labels  on  “other”  function  keys 

li 

num 

Number  of  lines  on  screen  or  page 

11 

str 

Last  line,  first  column  (if  no  cm) 

ma 

str 

Arrow  key  map,  used  by  vi  version  2  only 

md 

str 

Enter  bold  mode 

me 

str 

Turn  off  all  attributes,  normal  mode 

mb 

str 

Enter  dim  mode 

mi 

bool 

Safe  to  move  while  in  insert  mode 

ml 

str 

Memory  lock  on  above  cursor. 

mr 

str 

Enter  reverse  mode 

ms 

bool 

Safe  to  move  while  in  standout  and  underline  mode 

mu 

str 

Memory  unlock  (turn  off  memory  lock). 
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DC 

bool 

No  correctly  working  carriage  return  (DM2SOO,H2000) 

nd 

str 

Non-destructive  space  (cursor  right) 

nl 

str 

(P*) 

Newline  character  (default  \n) 

ns 

bool 

Terminal  is  a  CRT  but  doesn’t  scroll. 

08 

bool 

Terminal  overstrikes 

pc 

str 

Pad  character  (rather  than  null) 

pt 

bool 

Has  hardware  tabs  (may  need  to  be  set  with  Is) 

se 

str 

End  stand  out  mode 

sf 

str 

(P) 

Scroll  forwards 

Bg 

num 

Number  of  blank  chars  left  by  so  or  se 

SO 

str 

Begin  stand  out  mode 

sr 

str 

(P) 

Scroll  reverse  (backwards) 

ta 

str 

(P) 

Tab  (other  than  "'I  or  with  padding) 

tc 

str 

Entry  of  similar  terminal  -  must  be  last 

te 

str 

String  to  end  programs  that  use  cm 

ti 

str 

String  to  begin  programs  that  use  cm 

uc 

str 

Underscore  one  char  and  move  past  it 

ue 

str 

End  underscore  mode 

num 

Number  of  blank  chars  left  by  us  or  ue 

ul 

bool 

Terminal  underlines  even  though  it  doesn’t  overstrike 

up 

str 

Upline  (cursor  up) 

us 

str 

Start  underscore  mode 

vb 

str 

Visible  bell  (may  not  move  cursor) 

ve 

str 

Sequence  to  end  open/visual  mode 

vs 

str 

Sequence  to  start  open /visual  mode 

xb 

bool 

Beehive  (tl^escape,  f2=ctrl  C) 

xn 

bool 

A  newline  is  ignored  after  a  wrap  (Concept) 

xr 

bool 

Return  acts  like  ce  \r  \n  (Delta  Data) 

xs 

bool 

Standout  not  erased  by  writing  over  it  (HP  264?) 

xt 

bool 

Tabs  are  destructive,  magic  so  char  (Teleray  1061) 

A  Sample  Entry 

The  following  ent^,  which  describes  the  Concept-lOd,  is  among  the  more  complex  entries  in  the 
termcap  file  as  of  this  writing.  This  particular  concept  entry  is  outdated,  and  is  used  as  an  exam¬ 
ple  only.  jv. 

cl  1  clOO  1  conceptl00:is=\EU\Ef\E7\E5\E8\El\ENH\EK\E\200\Eo&\200:\ 

:al=3*\E'R:am:b8;cd=16*\E*C:ce=16\E*S:cl=:2**L:cm=\Ea%+  %+  :co#80:\ 

:dc=16\E‘A:dl=*3*\E‘B:ei=\E\200:eo;im=\ET:in;ip=16*:li#24:mi:nd=\E=:\ 

:8e=s\Ed\EJe:so=\ED\EE:ta=8\t:ul:up=s=\E;:vb=\Ek\EK:xn: 

Entries  may  continue,«nto  multiple  lines  by  giving  a  \  as  the  last  character  of  a  line,  and  empty 
fields  may  be  included  for  readability  (here  between  the  last  field  on  a  line  and  the  first  field  on 
the  next). 

Types  of  CApablUttes 

Capabilities  in  termeof  are  of  three  types:  Boolean  capabilities  which  indicate  that  the  terminal 
has  some  particular  feature,  numeric  capabilities  giving  the  size  of  the  terminal  or  the  size  of  par¬ 
ticular  delays,  and  string  capabilities,  which  give  a  sequence  which  can  be  used  to  perform  partic¬ 
ular  terminal  operations.  All  capabilities  have  two  letter  codes. 

Boolean  capabiliti^  are  introduced  simply  by  stating  the  t'wo-character  capability  code  in  the 
field  between  characters.  For  instance,  the  fact  that  the  Concept  has  '^automatic 
margins’’  (that  is,  an  automatic  return  and  linefeed  when  the  end  of  a  line  is  reached) 
is  indicated  by  the  capability  am.  Hence  the  description  of  the  Concept  includes  am. 
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capabilities  are  followed  by  the  character  and  then  the  value.  Thus  eo  which  indt* 
cates  the  number  of  columns  the  terminal  has  gives  the  value  ‘80*  for  the  Concept. 

valued  capabilities,  such  as  ce  (clear  to  end  of  line  sequence)  are  given  by  the  two 
character  code,  an  *«=’,  and  then  a  string  ending  at  the  next  following  A  delay  in 
milliseconds  may  appear  after  the  ‘s’  in  such  a  capability,  and  padding  characters  are 
supplied  by  the  editor  after  the  remainder  of  the  string  is  sent  to  provide  this  delay. 
The  delay  can  be  either  a  integer,  for  instance,  ‘20’,  or  an  integer  followed  by  an 
that  is,  *3*’.  A  indicates  that  the  padding  required  is  proportional  to  the  number 
of  lines  affected  by  the  operation,  and  the  amount  given  is  the  per*affected-unit  pad¬ 
ding  required.  When  a  ‘**  is  specified,  it  is  sometimes  useful  to  give  a  delay  of  the 
form  ‘3.5’  to  specify  a  delay  per  unit  to  tenths  of  milliseconds. 

A  number  of  escape  sequences  are  provided  in  the  string  valued  capabilities  for  easy 
encoding  of  characters  there.  A  \E  maps  to  an  escape  character,  ‘x  maps  to  a 
control-x  for  any  sq>propriate  x,  and  the  sequences  \n  \r  \t  \b  \f  give  a  newline, 
return,  tab,  backspace  and  formfeed.  Finally,  characters  may  be  given  as  three  octal 
digits  after  a  \,  and  the  characters  *  and  \  may  be  given  as  \‘  and  \\.  If  it  is  neces¬ 
sary  to  place  a  t  in  a  capability  it  must  be  escaped  in  octal  as  \072.  If  it  is  necessary 
to  place  a  null  character  in  a  string  capability  it  must  be  encoded  as  \200.  The  rou¬ 
tines  which  deal  with  termeap  use  C  strings,  and  strip  the  high  bits  of  the  output  very 
late  so  that  a  .\200  comes  out  as  a  \000  would. 

Preparing  Deserlptlona 

We  now  outline  how  to  prepare  descriptions  of  terminals.  The  most  effective  way  to  prepare  a 
terminal  description  is  by  imitating  the  description  of  a  similar  terminal  in  termeap  and  to  build 
up  a  description  gradually,  using  partial  descriptions  with  ex  to  cheek  that  they  are  correct.  Be 
aware  that  a  very  unusual  terminal  may  expose  deficiencies  in  the  ability  of  the  termeap  file  to 
describe  it  or  bags  in  ex.  To  easily  test  a  new  terminal  description  you  can  set  the  environment 
variable  TERMCAP  to  a  pathname  of  a  file  containing  the  description  you  are  working  on  and 
the  editor  will  look  there  rather  thmi  in  feteltermeap.  TERMCAP  can  also  be  set  to  the  termeap 
entry  itself  to  avoid  reading  the  file  when  starting  up  the  editor. 

Basle  capabiljtieh 

The  nuttlbbr  of  coiiimns  on  eacli  liill  for  the  terminal  is  given  by  the  eo  numeric  capability.  If 
the  terminal  is  a  CRT,  then  the  number  of  lines  on  the  screen  is  given  by  the  11  capability.  If  the 
terminal  wraps  around  to  the  beginning  of  the  next  line  when  it  reaches  the  right  margin,  then  it 
should  have  the  am  capability.  If  the  terminal  can  clear  its  screen,  then  this  is  given  by  the  el 
string  capability.  If  the  terminal  can  backspace,  then  it  should  have  the  bs  capability,  unless  a 
backspace  is  accomplished  by  a  character  other  than  (ugh)  in  which  case  you  should  give  this 
character  as  the  be  string  capability.  If  it  overstrikes  (rather  than  clearing  a  position  when  a 
character  is  struck  over)  then  it  should  have  the  os  capability. 

A  very  important  point  here  is  that  the  local  cursor  motions  encoded  in  termeap  are  undefined  at 
the  left  and  top  edges  of  a  CRT  terminal.  The  editor  will  never  attempt  to  backspace  around  the 
left  edge,  nor  will  it  attempt  to  go  up  locally  off  the  top.  The  editor  assumes  that  feeding  off  the 
bottom  of  the  screen  will  cause  the  screen  to  scroll  up,  and  the  am  capability  tells  whether  the 
cursor  sticks  at  the  right  edge  of  the  screen.  If  the  terminal  has  switch  selectable  automatic  mar¬ 
gins,  the  termeap  file  usually  assumes  that  this  b  on,  that  is,  am. 

These  capabilities  suffice  to  describe  hardcopy  and  “glass-tty”  terminab.  Thus  the  model  33  tele¬ 
type  is  described  as 

t3  [  33 1  tty33:co#72:o8 

while  the  Lear  Siegler  ADM-3  b  described  as 


Numerie 

String 
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cl|  admSjSjlsi  adm3:am:bs;cI='Z:li#24:co#80 

Cursor  addressing 

Cursor  addressing  in  the  terminal  is  described  by  a  cm  string  capability,  with  prtn^/(3S)  like 
escapes  %x  in  it.  These  substitute  to  encodings  of  the  current  line  or  column  position,  while 
other  characters  are  passed  through  unchanged.  If  the  cm  string  is  thought  of  as  being  a  func¬ 
tion,  then  its  arguments  are  the  line  and  then  the  column  to  which  motion  is  desired,  and  the  % 
encodings  have  the  following  meanings: 

%d  as  in  print/,  0  origin 
.%2  like%2d 
%3  like  %3d 
%.  like  %c 

%-f  X  adds  X  to  value,  then  %. 

%>xy  if  value  >  x  adds  y,  no  output. 

%t  reverses  order  of  line  and  column,  no  output 
%i  increments  line/column  (for  1  origin) 

%%  gives  a  single  % 

%n  exclusive  or  row  and  column  with  0140  (DM2500) 

%B  BCD  (16*(x/10))  +  (x%10),  no  output. 

%D  Reverse  coding  (x-2*(x%16)),  no  output.  (Delta  Data). 

Consider  the  HP2645,  which,  to  get  to  row  3  and  column  12,  needs  to  be  sent  \E&al2c03Y  pad¬ 
ded  for  6  milliseconds.  Note  that  the  order  of  the  rows  and  columns  is  inverted  here,  and  that 
the  row  and  column  are  printed  as  two  digits.  Thus  its  cm  capability  is 
“cm=»6\E&%r%2c%2Y”.  The  Microterm  ACT-IV  needs  the  current  row  and  column  sent  pre¬ 
ceded  by  a  'T,  with  the  row  and  column  simply  encoded  in  binary,  "cm— 'T%.%.”.  Terminals 
which  use  need  to  be  able  to  backspace  the  cursor  (be  or  be),  and  to  move  the  cursor  up 
one  line  on  the  screen  (up  introduced  below).  This  is  necessary  because  it  is  not  always  safe  to 
transmit  \t,  \ii  ‘D  and  \r,  as  the  system  may  change  or  discard  them. 

A  final  example  is  t&e  LSI  AOM-3a,  which  uses  row  and  column  offset  by  a  blank  character,  thus 
‘•cm«\E«%+  %+  ". 

Cursor  motions 

If  the  terminal  can  move  the  cursor  one  position  to  the  right,  leaving  the  character  at  the  current 
position  unchanged,  then  this  sequence  should  be  given  as  nd  (non-destructive  space).  If  it  can 
move  the  cursor  up  a  line  on  the  screen  in  the  same  column,  this  should  be  given  as  up.  If  the 
terminal  has  no  cursor  addressing  capability,  but  can  home  the  cursor  (to  very  upper  left  comer 
of  screen)  then  this  can  be  given  as  ho;  similarly  a  fast  way  of  getting  to  the  lower  left  hand 
corner  can  be  given  as  11;  this  may  involve  going  up  with  up  from  the  home  position,  but  the  edi¬ 
tor  will  never  do  this  itself  (unless  11  does)  because  it  makes  no  assumption  about  the  effect  of 
moving  up  from  tlib  home  position. 

Area  clears 

If  the  terminal  can  clear  from  the  current  position  to  the  end  of  the  line,  leaving  the  cursor  where 
it  is,  this  should  be  given  as  ee.  If  the  terminal  can  clear  from  the  current  position  to  the  end  of 
the  display,  then  this,  should  be  given  as  cd.  The  editor  only  uses  cd  from  the  first  column  of  a 
line.  t-: 

Iiuert/delete  Hue  "" 

If  the  terminal  can  open  a  new  blank  line  before  the  line  where  the  cursor  is,  this  should  be  given 
as  al;  this  is  done  only  from  the  first  position  of  a  line.  The  cursor  must  then  appear  on  the 
newly  blank  line.  If  the  terminsd  cmi  delete  the  line  which  the  cursor  is  on,  then  this  should  be 
given  as  dl;  this  is  done  only  from  the  first  position  on  the  line  to  be  deleted.  If  the  terminal  can 
scroll  the  screen  backwards,  then  this  can  be  given  as  ab,  but  just  aJ  suffices.  If  the  terminal  can 
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retain  display  memory  above  then  the  da  capabOity  should  be  given;  if  display  memory  can  be 
retained  below  then  db  should  be  given.  These  let  the  editor  understand  that  deleting  a  line  on 
the  screen  may  bring  non-blank  lines  up  from  below  or  that  scrolling  back  with  ab  may  bring 
down  non-blank  lines. 

Insert /delete  character 

There  are  two  basic  kinds  of  intelligent  terminals  with  respect  to  insert/delete  character  which 
can  be  described  using  iermcap.  The  most  common  insert/delete  character  operations  affect  only 
the  characters  on  the  current  line  and  shift  characters  off  the  end  of  the  line  rigidly.  Other  termi- 
nals,  such  as  the  Concept  100  and  the  Perkin  Elmer  Owl,  make  a  distinction  between  typed  and 
untyped  blanks  on  the  screen,  shifting  upon  an  insert  or  delete  only  to  an  untyped  blank  on  the 
screen  :which  is  either  eliminated,  or  expanded  to  two  untyped  blanks.  You  can  find  out  which 
kind  of  terminal  you  have  by  clearing  the  screen  and  then  typing  text  separated  by  cursor 
motions.  Type  “abc  def”  using  local  cursor  motions  (not  spaces)  between  the  “abc”  and  the 
^'def*.  Then  position  the  cursor  before  the  *'abc’’  and  put  the  terminal  in  insert  mode.  If  typing 
characters  causes  the  rest  of  the  line  to  shift  rigidly  and  characters  to  fall  off  the  end,  then  your 
terminal  does  not  distinguish  between  blanks  and  untyped  positions.  If  the  **abc”  shifts  over  to 
the  **der’  which  then  move  together  around  the  end  of  the  current  line  and  onto  the  next  as  you 
insert,  you  have  the  second  type  of  terminal,  and  should  give  the  capabQity  In,  which  stands  for 
^Insert  nulF*.  If  your  terminal  does  something  different  and  unusual  then  you  may  have  to 
modify  the  editor  to  get  it  to  use  the  insert  mode  your  terminal  defines.  We  have  seen  no  termi¬ 
nals  which  have  an  insert  mode  not  not  falling  into  one  of  these  two  classes. 

The  editor  can  handle  both  terminals  which  have  an  insert  mode,  and  terminals  which  send  a  sim¬ 
ple  sequence  to  open  a  blank  position  on  the  current  line.  Give  as  Im  the  sequence  to  get  into 
insert  mode,  of  give  it  an  empty  value  if  your  terminal  uses  a  sequence  to  insert  a  blank  position. 
Give  as  el  the  sequence  to  leave  insert  mode  (give  this,  with  an  empty  value  also  if  you  gave  Im 
so).  Now  give  as  Ic  any  sequence  needed  to  be  sent  just  before  sending  the  character  to  be 
inserted.  Most  terminab  with  a  true  insert  mode  will  not  give  te,  terminals  which  send  a 
sequence  to  open  a  screen  position  should  give  it  here.  (Insert  mode  is  preferable  to  the  sequence 
to  open  a  position  oh  the  screen  if  your  terminal  has  both.)  If  post  insert  padding  is  needed,  give 
thb  as  a  number  of  milliseconds  in  Ip  (a  string  option).  Any  other  sequence  which  may  need  to 
be  sent  after  an  insert  of  a  single  character  may  also  be  given  in  Ip. 

It  is  occasionally  necessary  to  move  around  white  in  insert  mode  to  delete  characters  on  the  same 
line  (for  example,  if  there  b  a  tab  after  the  insertion  position).  If  your  terminal  allows  motion 
while  in  insert  mode  you  can  give  the  capability  ml  to  speed  up  inserting  in  this  case.  Omitting 
ml  will  affect  only  speed.  Some  terminals  (notably  Datamediab)  must  not  have  ml  because  of 
the  way  their  insert  mode  works. 

Finally,  you  can  speciiy  delete  mode  by  giving  dm  and  ed  to  enter  and  exit  delete  mode,  and  dc 
to  delete  a  single  character  while  in  delete  mode. 

Highlighting!  underlining!  and  visible  bells 

If  your  terminal  has  sequences  to  enter  and  exit  standout  mode  these  can  be  given  as  so  and  se 
respectively.  If  there  are  several  flavors  of  standout  mode  (such  as  inverse  video,  blinking,  or 
underlining  -  half  bright  b  not  usually  an  acceptable  *  Standout’’  mode  unless  the  terminal  is  in 
inverse  video  mode  constantly)  the  preferred  mode  is  inverse  video  by  itself.  If  the  code  to 
change  into  or  out  of  standout  mode  leaves  one  or  even  two  blank  spaces  on  the  screen,  as  the 
TVI  912  and  Teleray  1061  do,  then  ug  should  be  given  to  tell  how  many  spaces  are  left. 

Codes  to  begin  underlining  and  end  underlining  can  be  given  as  ua  and  ua  respectively.  If  the 
terminal  has  a  code  to  underline  the  current  character  and  move  the  cursor  one  space  to  the  right, 
such  as  the  Microterm  Mime,  this  can  be  given  as  uc,  (If  the  underline  code  does  not  move  the 
cursor  to  the  right,  give.the  code  followed  by  a  nondestructive  space.) 
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Many  terminats,  such  as  the  HP  2621,  automatically  leave  standout  mode  when  they  move  to  a 
new  line  or  the  cursor  is  addressed.  Programs  using  standout  mode  should  exit  standout  mode 
before  moving  the  cursor  or  sending  a  newline. 

If  the  terminal  has  a  way  of  flashing  the  screen  to  indicate  an  error  quietly  (a  bell  replacement) 
then  this  can  be  given  as  vb;  it  must  not  move  the  cursor.  If  the  terminal  should  be  placed  in  a 
different  mode  during  open  and  visual  modes  of  ex,  this  can  be  given  as  vs  and  ve,  sent  at  the 
start  and  end  of  these  modes  respectively.  These  can  be  used  to  change,  for  example,  from  a 
underline  to  a  block  cursor  and  back. 

If  the  terminal  needs  to  be  in  a  special  mode  when  running  a  program  that  addresses  the  cursor, 
the  codes  to  enter  and  exit  this  mode  can  be  given  as  tl  and  te.  This  arises,  for  example,  from 
terminals  like  the  Concept  with  more  than  one  page  of  memory.  If  the  terminal  has  only  memory 
relative  cursor  addressing  and  not  screen  relative  cursor  addressing,  a  one  screen^sized  window 
must  be  flxed  into  the  terminal  for  cursor  addressing  to  work  properly. 

If  your  terminal  correctly  generates  underlined  characters  (with  no  special  codes  needed)  even 
though  it  does  not  overstrike,  then  you  should  give  the  capability  ul.  If  overstrikes  are  erasable 
with  a  blank,  then  this  should  be  indicated  by  giving  eo. 

ANSI  terminals  have  modes  for  the  character  highlighting.  Dim  characters  may  be  generated  in 
dim  mode,  entered  by  mb;  reverse  video  characters  in  reverse  mode,  entered  by  mr;  bold  charac¬ 
ters  in  bold  mode,  entered  by  mdj  and  normal  mode  characters  restored  by  turning  off  all  attri¬ 
butes  with  me. 

Keypad 

If  the  terminal  has  a  keypad  that  transmits  codes  when  the  keys  are  pressed,  this  information  can 
be  given.  Note  that  it  is  not  possible  to  handle  terminals  where  the  keypad  only  works  in  local 
(this  applies,  for  example,  to  the  unshifted  HP  2621  keys).  If  the  keypad  can  be  set  to  transmit 
or  not  transmit,  givq  these  codes  as  ka  and  ke.  Otherwise  the  keypad  is  assumed  to  always 
transmit.  The  codes  sent  by  the  left  arrow,  right  arrow,  up  arrow,  down  arrow,  and  home  keys 
can  be  given  as  kl,  kr»  ku,  kd>  and  kh  respectively.  If  there  are  function  keys  such  as  fO,  fl,  ..., 
f9,  the  codes  they  send  can  be  given  as  kO,  kl» ...»  k9.  If  these  keys  have  labels  other  than  the 
default  fO  through  f9,  the  labels  can  be  given  as  10,  11,  19.  If  there  are  other  keys  that 

transmit  the  same  code  as  the  terminal  expects  for  the  corresponding  function,  such  as  clear 
screen,  the  termeap  2  letter  codes  cmi  be  given  in  the  ko  capability,  for  example, 
“:ko=cl,ll,8f,8b:”,  which  says  that  the  terminal  has  clear,  home  down,  scroll  down,  and  scroll  up 
keys  that  transmit  the  same  thing  as  the  cl,  11,  sf,  and  sb  entries. 

The  ma  entry  is  also  -used  to  indicate  arrow  keys  on  terminals  which  have  single  character  arrow 
keys.  It  is  obsolete  but  still  in  use  in  version  2  of  vi,  which  must  be  run  on  some  minicomputers 
due  to  memory  limitations.  This  field  is  redundant  with  kl,  kr,  ku,  kd,  and  kh.  It  consists  of 
groups  of  two  characters.  In  each  group,  the  first  character  is  what  an  arrow  key  sends,  the 
second  character  is  the  corresponding  vi  command.  These  commands  are  h  for  kl,  J  for  kd,  k  for 
ku,  1  for  kr,  and  H  for  kh.  For  example,  the  mime  would  be  tmas:‘KJ*Zk'Xl:  indicating 
arrow  keys  left  (*H),  down  (‘K),  up  (‘Z),  and  right  (‘X).  (There  is  no  home  key  on  the  mime.) 

Mlseellaneoui 

If  the  terminal  requires  other  than  a  null  (zero)  character  as  a  pad,  then  this  can  be  given  as  pc. 

If  tabs  on  the  terminal  require  padding,  or  if  the  terminal  uses  a  character  other  than  ‘I  to  tab, 
then  this  can  be  given  as  ta. 

Hazeltine  terminals,  which  don’t  allow  characters  to  be  printed  should  indicate  hz.  Datamedia 
terminals,  which  echo  carriage-return  linefeed  for  carriage  return  and  then  ignore  a  following 
linefeed  should  indicate  nc.  Early  Concept  terminals,  which  ignore  a  linefeed  immediately  after 
an  am  wrap,  should  indicate  xn.  If  an  erase-eol  is  required  to  get  rid  of  standout  (instead  of 
merely  writing  on  top  of  it),  xs  should  be  given.  Teleray  terminals,  where  tabs  turn  all  characters 
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moved  over  to  bla&ks,  should  indicate  xt.  Other  specific  terminal  problems  may  be  corrected  by 
adding  more  capabilities  of  the  form  xx. 

Other  capabilities  include  In,  an  initialization  string  for  the  terminal,  and  If,  the  name  of  a  file 
containing  long  initialization  strings.  These  strings  are  expected  to  properly  clear  and  then  set 
the  tabs  on  the  terminal,  if  the  terminal  has  settable  tabs.  If  both  are  given,  Is  will  be  printed 
before  If.  This  is  useful  where  If  is  f  uarjlihl tahsetf stdhvX  Is  clears  the  tabs  first. 

Similar  Terminals 

If  there  are  two  very  similar  terminals,  one  can  be  defined  as  being  just  like  the  other  with  certain 
exceptions.  The  string  capability  te  can  be  given  with  the  name  of  the  similar  terminal.  This 
capability  must  be  last  and  the  combined  length  of  the  two  entries  must  not  exceed  1024.  Since 
termlib  routines  search  the  entry  from  left  to  right,  and  since  the  tc  capability  is  replaced  by  the 
corresponding  entry,  the  capabilities  given  at  the  left  override  the  ones  in  the  similar  terminal.  A 
capability  can  be  canceled  with  xxO  where  xx  is  the  capability.  For  example,  the  entry 

hn  1 2621nl:k8Q:keQ:tc=2621: 

defines  a  2621nl  that  does  not  have  the  ks  or  ke  capabilities,  and  hence  does  not  turn  on  the 
function  key  labels  when  in  visual  mode.  This  is  useful  for  different  modes  for  a  terminal,  or  for 
different  user  preferences. 

FILES 

/etc/termcap  file  containing  terminal  descriptions 
SEE  ALSO 

ex(l),  curse8(3X),  termcap(3X),  tset(l),  vi(l),  ul(l),  more(l) 

BUGS 

Ex  allows  only  256  characters  for  string  capabilities,  and  the  routines  in  termeap{SX)  do  not  check 
for  overflow  of  this  buffer.  The  total  length  of  a  single  entry  (excluding  only  escaped  newlines) 
may  not  exceed  1024. 

The  ms,  vs,  and  ve  entries  are  speciflc  to  the  vi  program. 

Not  all  programs  support  all  entries.  There  are  entries  that  are  not  supported  by  any  program. 
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NAME 

tp  -  DEC/mag  tape  formats 


DESCRIPTION 

Tp  dumps  files  to  and  extracts  files  from  DECtape  and  magtape.  The  formats  of  these  tapes  are 
the  same  except  that  magtapes  have  larger  directories. 

Block  zero  contains  a  copy  of  a  stand-alone  bootstrap  program.  See  reboot(8). 

Blocks  1  through  24  for  DECtape  (I  through  62  for  magtape)  contain  a  directory  of  the  tape. 
There  are  192  (reap.  496)  entries  in  the  directory;  8  entries  per  block;  64  bytes  per  entry.  Each 
entry  has  the  following  format: 


struct  { 

char 

unsigned  short 

char 

char 

char 

char 

long 

unsigned  short 
char 

unsigned  short 

h 


pathname(32j; 

mode; 

uid; 

gW; 

unused  1; 

8ize[3]; 

modtime; 

tapeaddr; 

unused  2|16]; 

checksum; 


The  path  name  ent^'  is  the  path  name  of  the  file  when  put  on  the  tape.  If  the  pathname  starts 
with  a  zero  word,  the  entry  is  empty.  It  is  at  most  32  bytes  long  and  ends  in  a  null  byte.  Mode, 
uid,  gid,  size  and  time  modified  are  the  same  as  described  under  t-nodes  (see  file  system  /s(5)). 
The  tape  address  is  the  tape  block  number  of  the  start  of  the  contents  of  the  file.  Every  file 
starts  on  a  block  boundary.  The  file  occupies  (size-)*  511)/512  blocks  of  continuous  tape.  The 
checksum  entry  has  a  value  such  that  the  sum  of  the  32  words  of  the  directory  entry  is  zero. 


Blocks  above  25  (resp,  63)  are  available  for  file  storage. 
A  fake  entry  has  a  size  of  zero. 


SEE  ALSO 

f8(5),  tp(l) 

BUGS 

The  pathname,  uid,  gid,  and  size  fields  are  too  smaU. 
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NAME 

ttys  -  terminal  initialization  data 
DESCRIPTION 

The  ttys  file  is  read  by  the  init  program  and  specifies  which  terminal  special  files  are  to  have  a 
process  created  for  them  so  that  people  can  log  in.  There  is  one  line  in  the  ttys  file  per  special  file 
associated  with  a  terminal. 

The  first  character  of  a  line  in  the  ttys  file  is  either  *0’  or  '1*.  If  the  first  character  on  the  line  is  a 
‘O’,  the  init  program  ignores  that  line.  If  the  first  character  on  the  line  is  a  ‘1’,  the  init  program 
creates  a  login  process  tor  that  line. 

The  second  character  on  each  line  is  used  as  an  argument  to  getty(8),  which  performs  such  tasks 
as  baud-rate  recognition,  reading  the  login  name,  and  calling  loyin.  For  normal  lines,  the  second 
character  is  ‘O’;  other  characters  can  be  used,  for  example,  with  hard-wired  terminals  where  speed 
recognition  is  unnecessary  or  which  have  special  characteristics.  The  remainder  of  the  line  is  the 
terminal’s  entry  in  the  device  directory,  /dev. 

Getty  uses  the  second  character  in  the  ttys  file  to  look  up  the  characteristics  of  the  terminal  in  the 
fetc/gettytab  file.  Consult  the  manual  page  for  an  explanation  of  the  layout  of 

f  etcf  gettytah, 

FILES 

/etc/ttys 
SEE  ALSO 

init(8),  getty(8),  login(l),  gettytab(5) 
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NAME 

ttytype  -  data  base  of  tenninal  types  by  port 

SYNOPSIS 

/ete/ttytype 

DESCRIPTION 

Ttytype  is  a  database  containing,  for  each  tty  port  on  the  system,  the  kind  of  terminal  that  is 
attached  to  it.  There  is  one  line  per  port,  containing  the  terminal  kind  (as  a  name  listed  in 
termed  (5)),  a  space,  and  the  name  of  the  tty,  minus  /dev/. 

This  information  is  read  by  and  by  lojr»n(l)  to  initialize  the  TfSlM  variable  at  login  time. 

SEE  ALSO 

tset(l),  login(l) 

BUGS 

Some  lines  are  merely  known  as  "dialup”  or  "plugboard”. 
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NAME 

uuencode  -  format  of  an  encoded  uuencode  file 
DESCRIPTION 

Piles  output  by  uuencode(lC)  consist  of  a  header  line,  followed  by  a  number  of  body  lines,  and  a 
trailer  line.  Uudtcodt  will  ignore  any  lines  preceding  the  header  or  following  the  trailer.  Lines 
preceding  a  header  must  not,  of  course,  look  like  a  header. 

The  header  line  is  distinguished  by  having  the  first  6  characters  “begin  The  word  begin  is  fol¬ 
lowed  by  a  mode  (in  octal),  and  a  string  which  names  the  remote  file.  Spaces  separate  the  three 
items  in  the  header  line. 

The  body  consists  of  a  number  of  lines,  each  at  most  62  characters  long  (including  the  trailing 
newline).  These  consist  of  a  character  count,  followed  by  encoded  characters,  followed  by  a  new- 
line.  The  character  count  is  a  single  printing  character,  and  represents  an  integer,  the  number  of 
bytes  the  rest  of  the  line  represents.  Such  integers  are  always  in  the  range  from  0  to  63  and  can 
be  determined  by  subtracting  the  character  space  (octal  40)  from  the  character. 

Groups  of  3  bytes  ^e  stored  in  4  characters,  6  bits  per  character.  All  are  offset  by  a  space  to 
make  the  characters  printing.  The  last  line  may  be  shorter  than  the  normal  45  bytes.  If  the  size 
is  not  a  multiple  of  3,  this  fact  can  be  determined  by  the  value  of  the  count  on  the  last  line. 
Extra  garbage  will  be  included  to  make  the  character  count  a  multiple  of  4.  The  body  is  ter¬ 
minated  by  a  tine  with  a  count  of  zero.  This  line  consists  of  one  ASCII  space. 

The  trailer  line  consists  of  “end“  on  a  line  by  itself. 

SEE  ALSO 

uuencode(lC),  uudecode(lC),  uusend(lC),  ttucp(lC),  mail(l) 
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NAME 

vfont  -  font  formats 
SYNOPSIS 

#hiclttde  <vfont.h> 

DESCRIPTION 

The  fonts  used  by  the  window  system  and  printer/plotters  have  the  following  format.  Each  font 
is  in  a  file,  which  contains  a  header,  an  array  of  character  description  structures,  and  an  array  of 
bytes  containing  the  bit  maps  for  the  characters.  The  header  has  the  following  format; 


struct  header  { 

short  magic; 

unsigned  short  size; 
short  maxx; 

short  maxy; 

short  xtend; 

}; 

#define  VFONT^MAGIC 


/♦  Magic  number  VFONT.MAGIC  •/ 
/*  Total  #  bytes  of  bitmaps  ♦/ 
j*  Maximum  horizontal  glyph  size  */ 
f*  Maximum  vertical  glyph  size 
I*  (unused)  */ 

0436 


Maxx  and  maxy  are  intended  to  be  the  maximum  horizontal  and  vertical  size  of  any  glyph  in  the 
fontf  in  raster  lines*  (A  glyph  is  just  a  printed  representation  of  a  character,  in  a  particular  size 
and  font.)  The  size  is  the  total  size  of  the  bit  maps  for  the  characters  in  bytes.  The  xUnd  field  is 
not  cunently  used* 


After  the  header  is  an  array  of  NUM.DISPATCH  structures,  one  for  each  of  the  possible  charac¬ 
ters  in  the  font*  Each  element  of  the  array  has  the  form: 


sihict  dispatch  | 

unsigned  short  addr; 
short  nbytes; 

char  up,  down,  left,  right; 

short  width; 

); 

#define  NUM_DISPATCH 


/•  &(giyph)  -  &(start  of  bitmaps)  *j 
f*  bytes  of  glyphs  (0  if  no  glyph)  ♦/ 
/*  Widths  from  baseline  point 
/*  Logical  width,  used  by  troff  */ 

256 


The  nhyitz  field  is  nonzero  for  characters  which  actually  exist.  For  such  characters,  the  addr  field 
is  an  offset  into  the  bit  maps  to  where  the  character's  bit  map  begins.  The  up,  down,  left,  and 
right  fields  are  offsets  from  the  base  point  of  the  glyph  to  the  edges  of  the  rectangle  which  the  bit 
map  represents*  (The  imaginary  ‘^base  point"  is  a  point  which  is  vertically  on  the  ''base  line"  of 
the  glyph  (the  bottom  line  of  a  glyph  which  doesn't  have  a  descender)  and  horizontally  near  the 
left  edge  of  the  glyph;  often  3  or  so  pixels  past  the  left  edge.)  The  bit  map  contains  up-t  down 
rows  of  data  for  the  character,  each  of  which  has  hfi’-h  right  columns  (bits).  Each  row  is  rounded 
up  to  a  number  of  bytes.  The  width  field  represents  the  logical  width  of  the  glyph  in  bits,  and 
shows  the  horizontal  displacement  to  the  base  point  of  the  next  glyph. 


FILES 

/usr/lib/vfont/* 

/usr/suntool/flxedwidthfonts/* 


SEE  ALSO 

troff(l),  pti(l),  vfontinfo(l),  vswap(l) 

BUGS 

A  machine-independent  font  format  should  be  defined*  The  shorts  in  the  above  structures  con¬ 
tain  different  bit  patterns  depending  whether  the  font  file  is  for  use  on  a  Vax  or  a  Sun.  The 
vewap  program  must  be  used  to  convert  one  to  the  other. 
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Interprocess  Communication  Primer 


This  document  provides  an  introduction  to  the  interprocess  communication  facilities  included  in 
the  Sun  Workstation  version  of  the  UNIXf  operating  system. 

It  discusses  the  overall  model  for  interprocess  communication  and  introduces  the  interprocess 
communication  primitives  which  have  been  added  to  the  system.  The  majority  of  the  document 
considers  the  use  of  these  primitives  in  developing  applications.  The  reader  is  expected  to  be 
familiar  with  the  C  programming  language  as  all  examples  are  written  in  C. 


f  UNK  is  s  trademark  of  Bell  Laboratories. 
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1.  Introduction 

One  of  the  most  important  features  added  in  the  Berkeley  4.2  release  of  the  UNIX  operating 
system  is  substantial  new  interprocess  communication  facilities.  These  facilities  are  the  result  of 
more  than  two  years  of  discussion  and  research.  The  facilities  provided  in  thb  release  incor* 
porate  many  of  the  ideas  from  current  research,  while  trying  to  maintain  the  UNIX  philosophy 
of  simplicity  and  conciseness.  We  hope  that  these  interprocess  communication  facilities  will 
establish  a  standard.  From  the  response  to  the  design,  it  appears  that  it  is  being  adopted  on 
many  systems. 

UNIX  has  previously  been  very  weak  in  the  area  of  interprocess  communication.  Until  recently, 
the  only  standard  mechanism  which  allowed  two  processes  to  communicate  were  pipes  (the  mpx 
files  which  were  part  of  Version  7  were  experimental).  Unfortunately,  pipes  are  restrictive  in 
that  the  two  communicating  processes  must  be  related  through  a  common  ancestor.  Further, 
the  semantics  of  pipes  makes  them  almost  impossible  to  maintain  in  a  distributed  environment. 

Earlier  attempts  at  extending  the  ipc  facilities  of  UNIX  have  met  with  mixed  reaction.  The 
majority  of  the  problems  have  been  related  to  the  fact  these  facilities  have  been  tied  to  the 
UNIX  file  system;  either  through  naming,  or  implementation.  Consequently,  the  ipc  facilities 
provided  in  this  release  have  been  designed  as  a  totally  independent  subsystem,  and  allow 
processes  to  rendezvous  in  many  ways.  Processes  may  rendezvous  through  a  UNIX  file  system- 
like  name  space  (a  space  where  all  names  are  path  names)  as  well  as  through  a  network  name 
space.  In  fact,  new  name  spaces  may  be  added  at  a  future  time  with  only  minor  changes  visible 
to  users.  Further,  the  communication  facilities  have  been  extended  to  included  more  than  the 
simple  byte  stream  provided  by  a  pipe-like  entity.  These  extensions  have  resulted  in  a  com¬ 
pletely  new  part  of  the  system  which  users  will  need  time  to  familiarize  themselves  with.  It  is 
likely  that  as  more  use  is  made  of  these  facilities  they  will  be  refined;  only  time  will  tell. 

The  remainder  of  this  document  is  organized  in  four  sections.  Section  2  introduces  the  new  sys¬ 
tem  calls  and  the  basic  model  of  communication.  Section  3  describes  some  of  the  supporting 
library  routines  users  may  find  useful  in  constructing  distributed  applications.  Section  4  is  con¬ 
cerned  with  the  client/server  model  used  in  developing  applications  and  includes  examples  of 
the  two  major  types  of  servers.  Section  5  delves  into  advanced  topics  which  sophisticated  users 
are  likely  to  encounter  when  using  the  ipc  facilities. 
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2.  Basics 

The  basic  building  block  for  communication  is  the  socket.  A  socket  is  an  endpoint  of  communi¬ 
cation  to  which  a  name  may  be  bound.  Each  socket  in  use  has  a  tjfpe  and  one  or  more  associ¬ 
ated  processes.  Sockets  exist  within  communication  domains.  A  communication  domain  is  an 
abstraction  introduced  to  bundle  common  properties  of  processes  communicating  through  sock¬ 
ets.  One  such  property  is  the  scheme  used  to  name  sockets.  For  example,  in  the  UNIX  com¬ 
munication  domain  sockets  are  named  with  UNIX  path  names;  e.g.  a  socket  may  be  named 
“/dev/foo”.  Sockets  normally  exchange  data  only  with  sockets  in  the  same  domain  (it  may  be 
possible  to  cross  domain  boundaries,  but  only  if  some  translation  process  is  performed).  The  ipc 
supports  two  separate  communication  domains:  the  UNIX  domain,  and  the  Internet  domain  is 
used  by  processes  which  communicate  using  the  the  DARPA  standard  communication  protocols. 
The  underlying  communication  facilities  provided  by  these  domains  have  a  significant  influence 
on  the  internal  system  implementation  as  well  as  the  interface  to  socket  facilities  available  to  a 
user.  An  example  of  the  latter  is  that  a  socket  "operating”  in  the  UNIX  domain  sees  a  subset 
of  the  possible  error  conditions  which  are  possible  when  operating  in  the  Internet  domain. 


2.1.  Socket  Types 

Sockets  are  typed  according  to  the  communication  properties  visible  to  a  user.  Processes  are 
presumed  to  communicate  only  between  sockets  of  the  same  type,  although  there  is  nothing 
that  prevents  communication  between  sockets  of  different  types  should  the  underlying  commun¬ 
ication  protocols  support  this. 

Three  types  of  sockets  currently  are  available  to  a  user.  A  stream  socket  provides  for  the 
bidirectional,  reliable,  sequenced,  and  unduplicated  flow  of  data  without  record  boundaries. 
Aside  from  the  bidirectionality  of  data  flow,  a  pair  of  connected  stream  sockets  provides  an 
interface  nearly  identical  to  that  of  pipes*. 

A  datagram  socket  supports  bidirectional  flow  of  data  which  is  not  promised  to  be  sequenced, 
reliable,  or  unduplicated.  That  is,  a  process  receiving  messages  on  a  datagram  socket  may  find 
messages  duplicated,  and,  possibly,  in  an  order  different  from  the  order  in  which  it  was  sent.  An 
important  characteristic  of  a  datagram  socket  is  that  record  boundaries  in  data  are  preserved. 
Datagram  sockets  closely  model  the  facilities  found  in  many  contemporary  packet  switched  net¬ 
works  such  as  the  Ethernet. 

A  raw  socket  provides  users  access  to  the  underlying  communication  protocols  which  support 
socket  abstractions.  These  sockets  are  normally  datagram  oriented,  though  their  exact  charac¬ 
teristics  are  dependent  on  the  interface  provided  by  the  protocol.  Raw  sockets  are  not  intended 
for  the  general  user;  they  have  been  provided  munly  for  those  interested  in  developing  new 
communication  protocols,  or  for  gaining  access  to  some  of  the  more  esoteric  facilities  of  an  exist¬ 
ing  protocol. 

Two  potential  socket  types  which  have  interesting  properties  are  the  sequenced  packet  socket 
and  the  reiiablg  delivered  message  socket.  A  sequenced  packet  socket  is  identical  to  a  stream 
socket  with  the  exception  that  record  boundaries  are  preserved.  This  interface  is  very  similar  to 
that  provided  by  the  Xerox  NS  Sequenced  Packet  protocol.  The  reliably  delivered  message 
socket  has  similar  properties  to  a  datagram  socket,  but  with  reliable  delivery.  While  these  two 
socket  types  have  been  loosely  defined,  they  are  not  currently  implemented.  So,  in  this 

*  In  the  UI0C  dom&in,  in  fnet,  the  semantics  are  identical  and,  as  one  might  expect,  pipes  have 
been  implemented  internally  as  simply  a  pmr  of  connected  stream  sockets. 
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document,  we  will  concern  ourselves  only  with  the  three  supported  socket  types. 


2.2.  Socket  Creation 

To  create  a  socket  the  socket  system  call  is  used: 

8  —  3ocket(domain,  type,  protocol); 

This  call  requests  that  the  system  create  a  socket  in  the  specified  domain  and  of  the  specified 
type.  A  particular  protocol  may  also  be  requested.  If  the  protocol  is  left  unspecified  (a  value  of 
0),  the  system  will  select  an  appropriate  protocol  from  those  protocols  which  comprise  the  com¬ 
munication  domain  and  which  may  be  used  to  support  the  requested  socket  type.  The  user  is 
returned  a  descriptor  (a  small  integer  number)  which  may  be  used  in  later  system  calls  which 
operate  on  sockets.  The  domain  is  specified  as  one  of  the  manifest  constants  defined  in  the  file 
<sysj8ocket.h>.  For  the  UNIX  domain  the  constant  is  AF.UNIX*;  for  the  Internet  domain 
AF_INET.  The  socket  types  are  also  defined  in  this  file  and  one  of  SOCK_STREAM, 
SOCK_DGRAM,  or  SOCK_RAW  must  be  specified.  To  create  a  stream  socket  in  the  Internet 
domain  the  following  call  might  be  used: 

s  =  socket(AFJNET,  SOCK.STREAM,  0); 

This  call  would  result  in  a  stream  socket  being  created  with  the  TCP  protocol  providing  the 
underlying  communication  support.  To  create  a  datagram  socket  for  on-machine  use  a  sample 
call  might  be: 

s  =  8ocket(AF_UNIX,  SOCK.DGRAM,  0); 

To  obtain  a  particular  protocol  one  selects  the  protocol  number,  as  defined  within  the  communi¬ 
cation  domain.  For  the  Internet  domain  the  available  protocols  are  defined  in  Knetinetf  in.h> 
or,  better  yet,  one  may  use  one  of  the  library  routines  discussed  in  section  3,  such  as  getproto- 
byname: 

^include  <sys/types.h> 

#include  <sys/socket.h> 

#include  <netinet/in.h> 

^include  <netdb.h> 

PP  —  getprotobyname(’’ tcp” ); 

s  =  socket(AF_INET,  SOCK_STREAM,  pp->p_proto); 

There  are  several  reasons  a  socket  call  may  fail.  Aside  from  the  rare  occurrence  of  lack  of 
memory  (ENOBUFS),  a  socket  request  may  fail  due  to  a  request  for  an  unknown  protocol 
(EPROTONOSUPPORT),  or  a  request  for  a  type  of  socket  for  which  there  is  no  supporting 
protocol  (EPROTOTYPE). 


*  The  manifest  constants  are  named  AF.whatever  as  they  indicate  the  “address  format*’  to  use  in 
interpreting  names. 
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2.3.  Binding  Names 

A  socket  is  created  without  a  name.  Until  a  name  is  bound  to  a  socket,  processes  have  no  way 
to  reference  it  and,  consequently,  no  messages  may  be  received  on  it.  The  bind  call  is  used  to 
assign  a  name  to  a  socket: 

bind(s,  name,  namelen); 

The  bound  name  is  a  variable  length  byte  string  which  is  interpreted  by  the  supporting 
protocol(s).  Its  interpretation  may  vary  from  communication  domain  to  communication  domain 
(this  is  one  of  the  properties  which  comprise  the  “domain").  In  the  UNIX  domain  names  are 
path  names  while  in  the  Internet  domain  names  contain  an  Internet  address  and  port  number. 
If  one  wanted  to  bind  the  name  “/dev/foo"  to  a  UNIX  domain  socket,  the  following  would  be 
used: 

#include  <sys/un.h> 
struct  sockaddrjun  sun; 
sun.sun_family  —  AF_UNIX; 

8trcpy(sun.sun_path,  "/dev/foo”); 
bin(l(s,  &3un,  strlen(” /dev/foo” )+  2); 

In  binding  an  Internet  address  things  become  more  complicated.  The  actual  call  is  simple, 

^include  <sys/types.h> 

^include  <netinet/in.h> 

struct  sockaddr_in  sin; 

bind(s,  £:sin,  siseof  (sin)); 

but  the  selection  of  what  to  place  in  the  address  sin  requires  some  discussion.  We  will  come 
back  to  the  problem  of  formulating  Internet  addresses  in  section  3  when  the  library  routines 
used  in  name  resolution  are  discussed. 


2.4.  Connection  Establishment 

With  a  bound  socket  it  is  possible  to  rendezvous  with  an  unrelated  process.  This  operation  is 
usually  asymmetric  with  one  process  a  “client"  and  the  other  a  “server".  The  client  requests 
services  from  the  server  by  initiating  a  “connection"  to  the  server’s  socket.  The  server,  when 
willing  to  offer  its  advertised  services,  passively  “listens"  on  its  socket.  On  the  client  side  the 
connect  call  is  used  to  initiate  a  connection.  Using  the  UNIX  domain,  this  might  appear  as, 

struct  sockaddr_un  server; 

connects,  &server,  strlen(server.8un_path)+  2); 

while  in  the  Internet  dommn, 

struct  sockaddr_in  server; 
connect(s,  feserver,  sizeof  (server)); 

If  the  client  process’s  socket  is  unbound  at  the  time  of  the  connect  call,  the  system  will 
automatically  select  and  bind  a  name  to  the  socket;  c.f.  section  5.4^.  An  error  is  returned  when 

I  You  mi)8t  do  a  iiet$oekn«me{2)  call  to  retrieve  the  binding. 
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the  connection  vias  unsuccessful  (any  name  automatically  bound  by  the  system,  however, 
remains).  Otherwise,  the  socket  is  associated  with  the  server  and  data  transfer  may  begin. 

Many  errors  can  be  returned  when  a  connection  attempt  fails.  The  most  common  are: 
ETIMEDOUT 

After  failing  to  establish  a  connection  for  a  period  of  time,  the  system  decided  there  was  no 
point  in  retrying  the  connection  attempt  any  more.  This  usually  occurs  because  the  desti* 
nation  host  is  down,  or  because  problems  in  the  network  resulted  in  transmissions  being 
lost. 

ECONNREFUSED 

The  host  refused  service  for  some  reason.  When  connecting  to  a  host  running  the  0.0 
release  version  of  UNIX  this  is  usually  due  to  a  server  process  not  being  present  at  the 
requested  name. 

ENETDOWN  or  EHOSTDOWN 

These  operational  errors  are  returned  based  on  status  information  delivered  to  the  client 
host  by  the  underlying  communication  service. 

ENETUNREACH  or  EHOSTUNREACH 

These  operational  errors  can  occur  either  because  the  network  or  host  is  unknown  (no  route 
to  the  network  or  host  is  present),  or  because  of  status  information  returned  by  intermedi* 
ate  gateways  or  switching  nodes.  Many  times  the  status  returned  is  not  sufficient  to  distin* 
guish  a  network  being  down  from  a  host  being  down.  In  these  cases  the  system  is  conservar 
tive  and  indicates  the  entire  network  is  unreachable. 

F  or  the  server  to  receive  a  client’s  connection  it  must  perform  two  steps  after  binding  its  socket. 
The  first  is  to  indicate  a  willingness  to  listen  for  incoming  connection  requests: 

listen(s,  5); 

The  second  parameter  to  the  listen  call  specifies  the  maximum  number  of  outstanding  connec¬ 
tions  which  may  be  queued  awaiting  acceptance  by  the  server  process.  Should  a  connection  be 
requested  while  the  queue  is  full,  the  connection  will  not  be  refused,  but  rather  the  individual 
messages  which  comprise  the  request  will  be  ignored.  This  gives  a  harried  server  time  to  make 
room  in  its  pending  connection  queue  while  the  client  retries  the  connection  request.  Had  the 
connection  been  returned  with  the  ECONNREFUSED  error,  the  client  would  be  unable  to  tell  if 
the  server  was  up  or  not.  As  it  is  now  it  is  still  possible  to  get  the  ETIMEDOUT  error  back, 
though  this  is  unlikely.  The  backlog  figure  supplied  with  the  listen  call  is  limited  by  the  system 
to  a  maximum  of  5  pending  connections  on  any  one  queue.  This  avoids  the  problem  of 
processes  hogging  system  resources  by  setting  an  infinite  backlog,  then  ignoring  all  connection 
requests. 

With  a  socket  marked  as  listening,  a  server  may  aeeepl  a  connection: 

fromlen  =  sizeof  (from); 

snew  =  accept(s,  &from,  &fromlen); 

A  new  descriptor  is  returned  on  receipt  of  a  connection  (along  with  a  new  socket).  If  the  server 
wishes  to  find  out  who  its  client  is,  it  may  supply  a  buffer  for  the  client  socket’s  name.  The 
value-result  parameter  fromlen  is  initialized  by  the  server  to  indicate  how  much  space  is  associ¬ 
ated  with  from,  then  modified  on  return  to  reflect  the  true  size  of  the  name.  If  the  client’s  name 
is  not  of  interest,  the  second  parameter  may  be  zero. 

Accept  normally  blocks.  That  is,  the  call  to  accept  will  not  return  until  a  connection  is  avail¬ 
able  or  the  system  call  is  interrupted  by  a  signal  to  the  process.  Further,  there  is  no  way  for  a 
process  to  indicate  it  will  accept  connections  from  only  a  specific  individual,  or  individuals.  It  is 
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up  to  the  user  process  to  consider  who  the  connection  is  from  and  close  down  the  connection  if 
it  does  not  wish  to  speak  to  the  process.  If  the  server  process  wants  to  accept  connections  on 
more  than  one  socket,  or  not  block  on  the  accept  call  there  are  alternatives;  they  will  be  com 
sidered  in  section  5. 


2.5.  Data  Transfer 

With  a  connection  established,  data  may  begin  to  flow.  To  send  and  receive  data  there  are  a 
number  of  possible  calls.  With  the  peer  entity  at  each  end  of  a  connection  anchored,  a  user  can 
send  or  receive  a  message  without  specifying  the  peer.  As  one  might  expect,  in  this  case,  then 
the  normal  read  and  write  system  calls  are  useable, 

write(s,  buf,  sizeof  (buf)); 
read(8,  buf,  sizeof  (buf)); 

In  addition  to  read  and  write,  the  new  calls  tend  and  recv  may  be  used: 

send(s,  buf,  sizeof  (buf),  flags); 
recv(s,  buf,  sizeof  (buf),  flags); 

While  tend  and  recv  are  virtually  identical  to  read  and  write,  the  extra  flagt  argument  is  import 
taut.  The  flags  may  be  specified  as  a  non-zero  value  if  one  or  more  of  the  following  is  required: 

MSGjOOB  send/receive  out  of  band  data 

MSG_PEEK  look  at  data  without  reading 

MSG_DONTROUTE  send  data  without  routing  packets 

Out  of  band  data  is  a  notion  specific  to  stream  sockets,  and  one  which  we  will  not  immediately 
consider.  The  option  to  have  data  sent  without  routing  applied  to  the  outgoing  packets  is 
currently  used  only  by  the  routing  table  management  process,  and  is  unlikely  to  be  of  interest 
to  the  casual  user.  The  ability  to  preview  data  is,  however,  of  interest.  When  MSG_PREVIEW 
is  specified  with  a  recv  call,  any  data  present  is  returned  to  the  user,  but  treated  as  still 
^^unread”.  That  is,  the  next  read  or  recv  call  applied  to  the  socket  will  return  the  data  previ¬ 
ously  previewed. 

2.6.  Discarding  Sockets 

Once  a  socket  is  no  longer  of  interest,  it  may  be  discarded  by  applying  a  dote  to  the  descriptor, 
close(s); 

If  data  is  associated  with  a  socket  which  promises  reliable  delivery  (e.g.  a  stream  socket)  when  a 
close  takes  place,  the  system  will  continue  to  attempt  to  transfer  the  data.  However,  after  a 
fairly  long  period  of  time,  if  the  data  is  still  undelivered,  it  will  be  discarded.  Should  a  user 
have  no  use  for  any  pending  data,  it  may  perform  a  thutdown  on  the  socket  prior  to  closing  it. 
This  call  is  of  the  form: 

shutdown(s,  how); 

where  how  b  0  if  the  user  is  no  longer  interested  in  reading  data,  1  if  no  more  data  will  be  sent, 
or  2  if  no  data  is  to  be  sent  or  received.  Applying  shutdown  to  a  socket  causes  any  data  queued 
to  be  immediately  discarded. 
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2.7.  Connectionless  Sockets 

To  this  point  we  have  been  concerned  mostly  with  sockets  which  follow  a  connection  oriented 
model.  However,  there  is  also  support  for  connectionless  interactions  typical  of  the  datagram 
facilities  found  in  contemporary  packet  switched  networks.  A  datagram  socket  provides  a  sym* 
metric  interface  to  data  exchange.  While  processes  are  still  likely  to  be  client  and  server,  there 
is  no  requirement  for  connection  establishment.  Instead,  each  message  includes  the  destination 
address. 

Datagram  sockets  are  created  as  before,  and  each  should  have  a  name  bound  to  it  in  order  that 
the  recipient  of  a  message  may  identify  the  sender.  To  send  data,  the  tendto  primitive  is  used, 

sendto(s,  buf,  buflen,  flags,  Ssto,  tolen); 

The  «,  buf,  buflen,  and  flags  parameters  are  used  as  before.  The  to  and  tolen  values  are  used  to 
indicate  the  intended  recipient  of  the  message.  When  using  an  unreliable  datagram  interface,  it 
is  unlikely  any  errors  will  be  reported  to  the  sender.  Where  information  is  present  locally  to 
recognize  a  message  which  may  never  be  delivered  (for  instance  when  a  network  is  unreachable), 
the  call  will  return  -1  and  the  global  value  errno  will  contain  an  error  number. 

To  receive  messages  on  an  unconnected  datagram  socket,  the  reevfrom  primitive  is  provided: 

recvfrom(8,  buf,  buflen,  flags,  &from,  &fromlen); 

Once  again,  the  fromlen  parameter  is  handled  in  a  value>result  fashion,  initially  contuning  the 
size  of  the  from  buffer. 

In  addition  to  the  two  calls  mentioned  above,  datagram  sockets  may  also  use  the  connect  call  to 
associate  a  socket  with  a  specific  address.  In  this  case,  any  data  sent  on  the  socket  will 
automatically  be  addressed  to  the  connected  peer,  and  only  data  received  from  that  peer  will  be 
delivered  to  the  user.  Only  one  connected  address  is  permitted  for  each  socket  (i.e.  no  multi* 
casting).  Connect  requests  on  datagram  sockets  return  immediately,  as  this  simply  results  in 
the  system  recording  the  peer's  address  (as  compared  to  a  stream  socket  where  a  connect 
request  initiates  establishment  of  an  end  to  end  connection).  Other  of  the  less  important  details 
of  datagram  sockets  are  described  in  section  S. 

2.8.  Input/Output  Multiplexing 

One  last  facility  often  used  in  developing  applications  is  the  ability  to  multiplex  i/o  requests 
among  multiple  sockets  and/or  files.  This  is  done  using  the  select  call: 

select(nfds,  fereadfds,  &writefds,  &execptfds,  &timeout); 

Select  takes  as  arguments  three  bit  masks,  one  for  the  set  of  file  descriptors  for  which  the  caller 
wishes  to  be  able  to  read  data  on,  one  for  those  descriptors  to  which  data  is  to  be  written,  and 
one  for  which  exceptional  conditions  are  pending.  Bit  masks  are  created  by  or>ing  bits  of  the 
form  “1  <<  fd”.  That  is,  a  descriptor  fd  is  selected  if  a  1  is  present  in  the  /<fth  bit  of  the 
mask.  The  parameter  nfds  specifies  the  range  of  file  descriptors  (i.e.  one  plus  the  value  of  the 
largest  descriptor)  specified  in  a  mask. 

A  timeout  value  may  be  specified  if  the  selection  is  not  to  last  more  than  a  predetermined 
period  of  time.  If  timeout  is  set  to  0,  the  selection  takes  the  form  of  a  poll,  returning  immedi¬ 
ately.  If  the  last  parameter  is  a  null  pointer,  the  selection  will  block  indefinitely*.  Select 

I  *  To  be  more  specific,  a  return  takes  place  only  when  a  descriptor  is  selectable,  or  when  a  sig¬ 
nal  is  received  by  the  caller,  interrupting  the  system  call. 
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normally  returns  the  number  of  file  descriptors  selected.  If  the  select  call  returns  due  to  the 
timeout  expiring,  then  a  value  of  -1  is  returned  along  with  the  error  number  EINTR. 

Select  provides  a  synchronous  multiplexing  scheme.  Asynchronous  notification  of  output  com¬ 
pletion,  input  availability,  and  exceptional  conditions  is  possible  through  use  of  the  SIGIO  and 
SIGURG  signals  described  in  section  5. 
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3.  Network  Library  Routines 

The  discussion  in  section  2  indicated  the  possible  need  to  locate  and  construct  network 
addresses  when  using  the  interprocess  communication  facilities  in  a  distributed  environment. 
To  aid  in  this  task  a  number  of  routines  haye  been  added  to  the  standard  C  run-time  library. 
In  this  section  we  will  consider  the  new  routines  provided  to  manipulate  network  addresses. 
While  the  Sun  system  release  networking  facilities  support  only  the  DARPA  standard  Internet 
protocols,  these  routines  have  been  designed  with  flexibility  in  mind.  As  more  communication 
protocols  become  available,  we  hope  the  same  user  interface  will  be  maintained  in  accessing 
network-related  address  data  bases.  The  only  difference  should  be  the  values  returned  to  the 
user.  Since  these  values  are  normally  supplied  the  system,  users  should  not  need  to  be  directly 
aware  of  the  communication  protocol  and/or  naming  conventions  in  use. 

Locating  a  service  on  a  remote  host  requires  many  levels  of  mapping  before  client  and  server 
may  communicate.  A  service  is  assigned  a  name  which  is  intended  for  human  consumption;  e.g. 
“the  login  server  on  host  monet”.  This  name,  and  the  name  of  the  peer  host,  must  then  be 
translated  into  network  addresses  which  are  not  necessarily  suitable  for  human  consumption. 
Finally,  the  address  must  then  used  in  locating  a  physical  location  and  route  to  the  service.  The 
specifics  of  these  three  mappings  is  likely  to  vary  between  network  architectures.  For  instance, 
it  is  desirable  for  a  network  to  not  require  hosts  be  named  in  such  a  way  that  their  physical 
location  is  known  by  the  client  host.  Instead,  underlying  services  in  the  network  may  discover 
the  actual  location  of  the  host  at  the  time  a  client  host  wishes  to  communicate.  This  ability  to 
have  hosts  named  in  a  location  independent  manner  may  induce  overhead  in  connection  estab¬ 
lishment,  as  a  discovery  process  must  take  place,  but  allows  a  host  to  be  physically  mobile 
without  requiring  it  to  notify  Its  clientele  of  its  current  location. 

Standard  routines  are  provided  for:  mapping  host  names  to  network  addresses,  network  names 
to  network  numbers,  protocol  names  to  protocol  numbers,  and  service  names  to  port  numbers 
and  the  appropriate  protocol  to  use  in  communicating  with  the  server  process.  The  file 
<.netdh.k>  must  be  included  when  using  any  of  these  routines. 


3.1.  Host  Names 

A  host  name  to  address  mapping  is  represented  by  the  hostent  structure: 


struct  hostent  { 
char 

*h„name; 

/  *  official  name  of  host  *  / 

char 

♦♦h_aliases; 

/*  alias  list  */ 

int 

h_addrtype; 

/  *  host  address  type  *  / 

int 

hjength; 

/♦  length  of  address  */ 

char 

*h_addr; 

/*  address  ♦/ 

Note  that  the  h_addr  field  in  the  structure  definition  is  defined  as  a  pointer  to  char.  In  the 
case  of  Internet  addresses  (the  only  case  implemeted  to  date)  you  should  cast  this  to  a  (atruet 
injaddr  *)  when  using  the  item. 

The  official  name  of  the  host  and  its  public  aliases  are  returned,  along  with  a  variable  length 
address  and  address  type.  The  routine  gethostbyname{3N)  takes  a  host  name  and  returns  a  Aos- 
tent  structure,  while  the  routine  gethostbyaddt{ZN)  maps  host  addresses  into  a  hostent  structure. 
It  is  possible  for  a  host  to  have  many  addresses,  all  having  the  same  name.  Gethostybyname 
returns  the  first  matching  entry  in  the  data  base  file  /etc/hosts}  if  this  is  unsuitable,  the  lower 
level  routine  seiAo»feni(3N)  may  be  used.  For  example,  to  obtain  a  hostent  structure  for  a  host 
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on  a  particular  network  the  following  routine  might  be  used  (for  simplicity,  only  Internet 
addresses  are  considered):  « 

^include  <sys/types.h> 
fi^include  <sys/socket.h> 
fj^include  <netinet/in.h> 

^include  <netdb.h> 

struct  hostent  * 

gethostbynameandnet(name,  net) 
char  *name; 
int  net; 

{ 

register  struct  hostent  *hp; 
register  char  ♦*cp; 

sethostent(0); 

while  ((hp  =  gethostentO)  !=>  NULL)  { 

if  (hp->h_addrtype  AF  JNET) 
continue; 

if  (strcmp(name,  hp*>h_name))  { 

for  (cp  =  hp->h_alia8es;  cp  &&  *cp  t=  NULL;  cp+  +  ) 
if  (stremp(name,  '^cp)  »»  0) 
goto  found; 
continue; 

) 

found: 

if  (in_netof( ♦(struct  in.addr  ♦)hp->h_addr))  »==  net) 
break; 

} 

endhostent(O); 
return  (hp); 

} 

(in_net0/(3N)  is  a  standard  routine  which  returns  the  network  portion  of  an  Internet  address.) 

3.2.  Network  Names 

As  for  host  names,  routines  for  mapping  network  names  to  numbers,  and  back,  are  provided. 
These  routines  return  a  netent  structure: 
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/♦ 

*  Assumption  here  is  that  a  network  number 

*  fits  in  32  bits  ~  probably  a  poor  one. 

*/ 

struct  netent  { 


char 

*n_name; 

/*  official  name  of  net  */ 

char 

♦  *n_aliases; 

/*  alias  list  */ 

int 

n_addrtype; 

/*  net  address  type  */ 

int 

njiet; 

/♦  network  #  ♦/ 

}; 

The  routines  getnetbyname{3N),  getnetbynumber{ZN),  and  ]re(nctenl(3N)  are  the  network  coun¬ 
terparts  to  the  host  routines  described  above. 

3.3.  Protocol  Names 

For  protocols  the  protoent  structure  defines  the  protocol-name  mapping  used  with  the  routines 
getprotobyname{3N),  getprotobynvmber{SN),  and  (refpretocn((3N): 

struct  protoent  { 

char  *p_name; 

char  *  *p_aliases; 

int  p_proto; 

}; 

3.4.  Service  Names 

Information  regarding  services  is  a  bit  more  complicated.  A  service  is  expected  to  reside  at  a 
specific  “port"  and  employ  a  particular  communication  protocol.  This  view  is  consistent  with 
the  Internet  domain,  but  inconsistent  with  other  network  architectures.  Further,  a  service  may 
reside  on  multiple  ports  or  support  multiple  protocols.  If  either  of  these  occurs,  the  higher  level 
library  routines  will  have  to  be  bypassed  in  favor  of  homegrown  routines  similar  in  spirit  to  the 
“gethostbynameandnet"  routine  described  above.  A  service  mapping  is  described  by  the  icrvent 
structure, 

struct  servent  { 


char 

*s_name; 

/*  official  service  name  ♦/ 

char 

**s_aliases; 

/•  alias  list  ♦/ 

int 

s_j)ort; 

/*  port  #  */ 

char 

*s_proto; 

/*  protocol  to  use  */ 

}; 

The  routine  9et«erv&yname(3N)  maps  service  names  to  a  servent  structure  by  specifying  a  ser¬ 
vice  name  and,  optionally,  a  qualifying  protocol.  Thus  the  call 

sp  ==  getservbyname(” telnet”,  (char  *)0); 

returns  the  service  specification  for  a  telnet  server  using  any  protocol,  while  the  cal! 
sp  =  getservbyname(” telnet”,  ”tcp”); 

returns  oply  that  telnet  server  which  uses  the  TCP  protocol.  The  routines  geUervbyport{3N) 


f*  official  protocol  name  *f 
f*  alias  list  ♦/ 

/♦  protocol  #  */ 
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and  9ct«ervenf(3N)  are  also  provided.  The  getaervbjfport  routine  has  an  interface  similar  to  that 
provided  by  gettervbyname;  an  optional  protocol  name  may  be  specified  to  qualify  lookups. 


3.5.  Miscellaneous 

\^^th  the  support  routines  described  above,  an  application  program  should  rarely  have  to  deal 
directly  'with  addresses.  This  allows  services  to  be  developed  as  much  as  possible  in  a  network 
independent  fashion.  It  is  clear,  however,  that  pur^ng  all  network  dependencies  is  very 
difficult.  So  long  as  the  user  is  required  to  supply  network  addresses  when  naming  services  and 
sockets  there  will  always  some  network  dependency  in  a  program.  For  example,  the  normal 
code  included  in  client  programs,  such  as  the  remote  login  program,  is  of  the  form  shown  in  Fig> 
ure  1.  (This  example  will  be  considered  in  more  detail  in  section  4.) 

If  we  wanted  to  make  the  remote  login  program  independent  of  the  Internet  protocols  and 
addressing  scheme  we  would  be  forced  to  add  a  layer  of  routines  which  masked  the  network 
dependent  aspects  from  the  mainstream  lo^n  code.  For  the  current  facilities  available  in  the 
system  this  does  not  appear  to  be  worthwhile.  Perhaps  when  the  system  is  adapted  to  different 
network  architectures  the  utilities  will  be  reorganized  more  cleanly. 

Aside  from  the  address>related  data  base  routines,  there  are  several  other  routines  available  in 
the  run-time  library  which  are  of  interest  to  users.  These  are  intended  mostly  to  simplify  mani¬ 
pulation  of  names  and  addresses.  Table  1  summarizes  the  routines  for  manipulating  variable 
length  byte  strings  and  handling  byte  swapping  of  network  addresses  and  'values. 

The  byte  swapping  routines  are  provided  because  the  operating  system  expects  addresses  to  be 
supplied  in  network  order.  On  a  VAX,  or  machine  with  similar  architecture,  this  is  usually 
reversed.  Consequently,  programs  are  sometimes  required  to  byte  swap  quantities.  The  library 
routines  which  return  network  addresses  provide  them  in  network  order  so  that  they  may  sim¬ 
ply  be  copied  into  the  structures  provided  to  the  system.  This  implies  users  should  encounter 
the  byte  swapping  problem  only  when  interpreting  network  addresses.  For  example,  if  an  Inter¬ 
net  port  is  to  be  printed  out  the  following  code  would  be  required: 
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^include  <8ys/types.h> 
^include  <sy s/socket. li> 
#include  <netinet/in.h> 
^include  <stdio.h> 

^include  <netdb.h> 

main(argc,  argy) 

char  *argv[]; 

{ 

struct  sockaddrjn  sin; 
struct  servent  *sp; 
struct  hostent  *hp; 
int  s; 


sp  =  getservbyname(’’ login",  "tcp"); 
if  (sp  ==  NULL)  { 

fprintf(stderr,  "riogin:  tep/Iogin:  unknown  8ervice\n"); 
exit(l); 

} 

hp  =  gethostbyname(argv(l]); 
if  (hp  NULL)  { 

fprintf(stderr,  "riogin:  %8:  unknown  ho8t\D”,  argv(l]); 
exit(2); 

> 

bzero((char  *)&sin,  sizeof  (sin)); 

bcopy(hp->h_addr,  (char  *)&sin.sin_addr,  hp->hjength); 

sin.sin_family  =  hp->h_addrtype; 

sin.sin_port  =  5p->s_port; 

s  =  socket(AF JNET,  SOCK.STREAM,  0); 

if  (s  <  0)  { 

perror("rlopn:  socket"); 
exit(3); 


if  (connect(s,  (char  *)&sin,  sizeof  (sin))  <  0)  { 
perror(" riogin:  connect"); 
exit(5); 


} 


Figure  1.  Remote  login  client  code. 


printf("port  number  %d\n",  ntohs(sp->s_port)); 

On  machines  other  than  the  VAX  these  routines  are  defined  as  null  macros. 
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Call 

Synopsis 

bcmp(sl,  82,  n) 

bcopy(sl,  82,  n) 

bzero(base,  n) 

htonl(val) 

htons(val) 

ntohl(val) 

ntohs(val) 

compare  byte-strings;  0  if  same,  not  0  otherwise 
copy  n  bytes  from  si  to  82 
zero-fill  n  bytes  starting  at  base 

convert  32-bit  quantity  from  host  to  network  byte  order 
convert  16-bit  quantity  from  host  to  network  byte  order 
convert  32-bit  quantity  from  network  to  host  byte  order 
convert  16-bit  quantity  from  network  to  host  byte  order 

Table  1.  C  run-time  routines. 

4.  Client/Servep  Model 

The  most  commonly  used  paradigm  in  constructing  distributed  applications  is  the  client/server 
model.  In  this  scheme  client  applications  request  services  from  a  server  process.  This  implies  an 
asymmetry  in  establishing  communication  between  the  client  and  server  which  has  been  exam¬ 
ined  in  section  2.  In  this  section  we  will  look  more  closely  at  the  interactions  between  client  and 
server,  and  consider  some  of  the  problems  in  developing  client  and  server  applications. 

Client  and  server  require  a  well  known  set  of  conventions  before  service  may  be  rendered  (and 
accepted).  This  set  of  conventions  comprises  a  protocol  which  must  be  implemented  at  both 
ends  of  a  connection.  Depending  on  the  situation,  the  protocol  may  be  symmetric  or  asym¬ 
metric.  In  a  symmetric  protocol,  either  side  may  play  the  master  or  slave  roles.  In  an  asym¬ 
metric  protocol,  one  side  is  immutably  recognized  as  the  master,  with  the  other  the  slave.  An 
example  of  a  symmetric  protocol  is  the  TELNET  protocol  used  in  the  Internet  for  remote  termi¬ 
nal  emulation.  An  example  of  an  asymmetric  protocol  is  the  Internet  file  transfer  protocol, 
FTP.  No  matter  whether  the  specific  protocol  used  in  obtaining  a  service  is  symmetric  or  asym¬ 
metric,  when  accessing  a  service  there  is  a  “client  process”  and  a  “server  process”.  We  will  first 
consider  the  properties  of  server  processes,  then  client  processes. 

A  server  process  normally  listens  at  a  well  know  address  for  service  requests.  Alternative 
schemes  which  use  a  service  server  may  be  used  to  eliminate  a  flock  of  server  processes  clogging 
the  system  while  remaining  dormant  most  of  the  time.  The  Xerox  Courier  protocol  uses  the 
latter  scheme.  When  using  Courier,  a  Courier  client  process  contacts  a  Courier  server  at  the 
remote  host  and  identifies  the  service  it  requires.  The  Courier  server  process  then  creates  the 
appropriate  server  process  based  on  a  data  base  and  “splices”  the  client  and  server  together, 
voiding  its  part  in  the  transaction.  This  scheme  is  attractive  in  that  the  Courier  server  process 
may  provide  a  single  contact  point  for  all  services,  as  well  as  carrying  out  the  initial  steps  in 
authentication.  However,  while  this  is  an  attractive  possibility  for  standardizing  access  to  ser¬ 
vices,  it  does  introduce  a  certain  amount  of  overhead  due  to  the  intermediate  process  involved. 
Implementations  which  provide  this  type  of  service  within  the  system  can  minimize  the  cost  of 
client  server  rendezvous. 


4.1.  Servers 

In  this  release,  most  servers  are  accessed  at  well  known  Internet  addresses  or  UNIX  domain 
names.  When  a  server  is  started  at  boot  time  it  advertises  it  services  by  listening  at  a  well 
know  location.  For  example,  the  remote  login  server’s  main  loop  is  of  the  form  shown  in  Figure 
2. 
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main(argc,  argv) 
int  argc; 
char  ♦♦argv; 

{ 

int  f; 

struct  sockaddr_in  from; 
struct  servent  ♦sp; 

sp  »==  getservbyname(’’ login”,  "tcp"); 
if  (sp  ==  NULL)  { 

fprintflfstdeiT,  "rlogind:  tcp/login:  unknoivn  8enrice\n”); 
exit(l); 

} 


#ifndef  DEBUG 

<<  disassociate  server  from  controlling  terminal  >> 

#endif 

8in.sin_port  =  sp->8_port; 
f  =  socket(AFJNET,  SOCK.STREAM,  0); 
if  (bind(f,  (caddr_t)&sin,  sizeof  (sin))  <  0)  { 

} 

listen(f,  5); 

for  (;;)  { 

int  g,  ten  =  sizeof  (from); 


} 


g  =  accept(f,  &from,  &len); 

if(g<0){ 

if  (ermo  !=  EINTR) 

perror(”rlogind:  accept”); 
continue; 

) 

if  (fork()  ==  0)  { 
close(f); 
doit(g,  &from); 

} 

close(g); 


Figure  2.  Remote  login  server. 


The  first  step  taken  by  the  server  is  look  up  its  service  definition: 

sp  =  getservbyname(”  login” ,  ”tcp”); 
if  (sp  ==  NULL)  { 


■  ^ 
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fprintf(8tderr,  "rlogind:  tcp/login:  unknown  8ervice\n”); 
exit(l); 


This  definition  is  used  in  later  portions  of  the  code  to  define  the  Internet  port  at  which  it  listens 
for  service  requests  (indicated  by  a  connection). 

Step  two  is  to  disassociate  the  server  from  the  controlling  terminal  of  its  invoker.  This  is 
important  as  the  server  will  likely  not  want  to  receive  signals  delivered  to  the  process  group  of 
the  controlling  terminal. 

Once  a  server  has  established  a  pristine  environment,  it  creates  a  socket  and  begins  accepting 
service  requests.  The  bind  call  is  required  to  insure  the  server  listens  at  its  expected  location. 
The  main  body  of  the  loop  is  fairly  simple: 


for  (;;)  { 


int  g,  len  —  sizeof  (from); 


g  =  accept(f,  &from,  &Ien); 

if  (g  <  0)  { 

if  (ermo  !=  EINTR) 

perror(” rlogind:  accept”); 
continue; 

} 

if  (fork()  ==  0)  { 
close(f); 

doit(g,  &from); 

} 

close(g); 

) 


An  accept  call  blocks  the  server  until  a  client  requests  service.  This  call  could  return  a  failure 
status  if  the  call  is  interrupted  by  a  signal  such  as  SIGCHLD  (to  be  discussed  in  section  5). 
Therefore,  the  return  value  from  accept  is  checked  to  insure  a  connection  has  actually  been  estap 
blished.  With  a  connection  in  hand,  the  server  then  forks  a  child  process  and  invokes  the  main 
body  of  the  remote  login  protocol  processing.  Note  how  the  socket  used  by  the  parent  for 
queueing  connection  requests  is  closed  in  the  child,  while  the  socket  created  as  a  result  of  the 
accept  is  closed  in  the  parent.  The  address  of  the  client  is  also  handed  the  doit  routine  because 
it  requires  it  in  authenticating  clients. 


4.2.  Clients 

The  client  side  of  the  remote  login  service  was  shown  earlier  in  Figure  1.  One  can  see  the 
separate,  asymmetric  roles  of  the  client  and  server  clearly  in  the  code.  The  server  is  a  passive 
entity,  listening  for  client  connections,  while  the  client  process  is  an  active  entity,  initiating  a 
connection  when  invoked. 

Let  us  consider  more  closely  the  steps  taken  by  the  client  remote  login  process.  As  in  the  server 
process  the  first  step  is  to  locate  the  service  definition  for  a  remote  login: 
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sp  =  getserv by name{’’ login”,  ”tcp”); 
if  (sp  ==  NULL)  { 

fprintf(8tderr,  "rlo^n:  tcp/login:  unknown  8ervice\n”)j 
exit(l); 

} 

Next  the  destination  host  is  looked  up  with  a  gethoatbynatne  call; 

hp  =  get  host  byname(argv[l]); 
if  (hp  =«=  NULL)  { 

fprintf(8tderr,  ”rlogin;  %s:  unknown  ho8t\n”,  argT[l]); 
exit(2); 

} 

With  this  accomplished,  all  that  is  required  is  to  establish  a  connection  to  the  server  at  the 
requested  host  and  start  up  the  remote  login  protocol.  The  address  buffer  is  cleared,  then  filled 
in  with  the  Internet  address  of  the  foreign  host  and  the  port  number  at  which  the  login  process 
resides: 

bzero((char  *)fcsin,  sizeof  (sin)); 

bcopy(hp->h_addr,  (char  *)sin.sin_addr,  hp->h_length); 
sin.sin_family  =  hp'>h_addrtype; 
sin.sin_port  =  sp->s_port; 

A  socket  is  created,  and  a  connection  initiated. 

s  =  socket(hp->h_addrtype,  SOCK_STREAM,  0); 
if  (s  <  0)  { 

perror(”rlogin:  socket”); 
exit(3); 

} 

if  (connect(3,  (char  *)&sin,  sizeof  (sin))  <  0)  { 
perror(”r!ogin:  connect”); 
exit(4); 

) 

The  details  of  the  remote  login  protocol  will  not  be  considered  here. 


4.3.  Connectionless  Servers 

While  connection'based  services  are  the  norm,  some  services  are  based  on  the  use  of  datagram 
sockets.  One,  in  particular,  is  the  “rwho”  service  which  provides  users  with  status  information 
for  hosts  connected  to  a  local  area  network.  This  service,  while  predicated  on  the  ability  to 
broadcaat  information  to  all  hosts  connected  to  a  particular  network,  is  of  interest  as  an  exam* 
pie  usage  of  datagram  sockets. 

A  user  on  any  machine  running  the  rwho  server  may  find  out  the  current  status  of  a  machine 
with  the  ruptime{l)  program.  The  output  generated  is  illustrated  in  Figure  3. 

Status  information  for  each  host  is  periodically  broadcast  by  rwho  server  processes  on  each 
machine.  The  same  server  process  also  receives  the  status  information  and  uses  it  to  update  a 
database.  This  database  is  then  interpreted  to  generate  the  status  information  for  each  host. 
Servers  operate  autonomously,  coupled  only  by  the  local  network  and  its  broadcast  capabilities. 


18 


Revision  E  of  7  January  1984 


Sun  System  Interface  Manual 


Interprocess  Communication  Primer 


arpa 

up 

9:45, 

5  users,  load 

1.15, 

1.39, 

1.31 

cad 

up 

2-1- 12:04, 

8  users,  load 

4.67, 

5.13, 

4.59 

calder 

up 

10:10, 

0  users,  load 

0.27, 

0.15, 

0.14 

dali 

up 

2-1-  06:28, 

9  users,  load 

1.04, 

1.20, 

1.65 

degas 

up 

25+  09:48, 

0  users,  load 

1.49, 

1.43, 

1.41 

ear 

up 

5+  00:05, 

0  users,  load 

1.51, 

1.54, 

1.56 

emie 

down 

0:24 

esvax 

down 

17:04 

Ingres 

down 

0:26 

kim 

up 

3+  09:16, 

8  users,  load 

2.03, 

2.46, 

3.11 

matisse 

up 

3+  06:18, 

0  users,  load 

0.03, 

0.03, 

0.05 

medea 

up 

3+  09:39, 

2  users,  load 

0.35, 

0.37, 

0.50 

merlin 

down 

19+  15:37 

miro 

up 

1+  07:20, 

7  users,  load 

4.59, 

3.28, 

2.12 

monet 

up 

1+  00:43, 

2  users,  load 

0.22, 

0.09, 

0.07 

oz 

down 

16:09 

statvax 

up 

2+  15:57, 

3  users,  load 

1.52, 

1.81, 

1.86 

ucbvax 

up 

9:34, 

2  users,  load 

6.08, 

5.16, 

3.28 

Figure  3.  ruptime  output. 


The  rwho  server,  in  a  simplified  form,  is  pictured  in  Figure  4.  There  are  two  separate  tasks  per* 
formed  by  the  server.  The  first  task  is  to  act  as  a  receiver  of  status  information  broadcast  by 
other  hosts  on  the  network.  This  job  is  carried  out  in  the  main  loop  of  the  program.  Packets 
received  at  the  rwho  port  are  interrogated  to  insure  they’ve  been  sent  by  another  rwho  server 
process,  then  are  time  stamped  with  their  arrival  time  and  used  to  update  a  file  indicating  the 
status  of  the  host.  When  a  host  has  not  been  heard  from  for  an  extended  period  of  time,  the 
database  interpretation  routines  assume  the  host  is  down  and  indicate  such  on  the  status 
reports.  This  algorithm  is  prone  to  error  as  a  server  may  be  down  while  a  host  is  actually  up, 
but  serves  our  current  needs. 

The  second  task  performed  by  the  server  is  to  supply  information  regarding  the  status  of  its 
host.  This  involves  periodically  acquiring  system  status  information,  packaging  it  up  in  a  mes¬ 
sage  and  broadcasting  it  on  the  local  network  for  other  rwho  servers  to  hear.  The  supply  func¬ 
tion  is  triggered  by  a  timer  and  runs  off  a  signal.  Locating  the  system  status  information  is 
somewhat  involved,  but  uninteresting.  Deciding  where  to  transmit  the  resultant  packet  does, 
however,  indicates  some  problems  with  the  current  protocol. 

Status  information  is  broadcast  on  the  local  network.  For  networks  which  do  not  support  the 
notion  of  broadcast  another  scheme  must  be  used  to  simulate  or  replace  broadcasting.  One  pos¬ 
sibility  is  to  enumerate  the  known  neighbors  (based  on  the  status  received).  This,  unfor¬ 
tunately,  requires  some  bootstrapping  information,  as  a  server  started  up  on  a  quiet  network 
will  have  no  known  neighbors  and  thus  never  receive,  or  send,  any  status  information.  This  is 
the  identical  problem  faced  by  the  routing  table  management  process  in  propagating  routing 
status  information.  The  standard  solution,  unsatisfactory  as  it  may  be,  is  to  inform  one  or 
more  servers  of  known  neighbors  and  request  that  they  always  communicate  with  these  neigh¬ 
bors.  If  each  server  has  at  least  one  neighbor  supplying  it,  status  information  may  then  pro¬ 
pagate  through  a  neighbor  to  hosts  which  are  not  (possibly)  directly  neighbors.  If  the  server  is 
able  to  support  networks  which  provide  a  broadcast  capability,  as  well  as  those  which  do  not, 
then  networks  with  an  arbitrary  topology  may  share  status  information*. 

1  ♦  One  must,  however,  be  concerned  about  “loops”.  That  is,  if  a  host  is  connected  to  multiple 
networks,  it  will  receive  status  information  from  itself.  Thb  can  lead  to  an  endless,  wasteful,  ex- 
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main() 

{ 

sp  =  getservbyname(”who”,  "udp”); 

net  —  getnetbyname(”  localnet" ); 

sin.sin_addr  =  inet_makeaddr(INADDR_ANY ,  net); 

sin.sin_port  =  8p->8_port; 

8  r=  socket(AFJNET,  SOCKJDGRAM,  0); 

bind(s,  &sin,  sizeof  (sin)); 

sigset{SIGALRM,  onalrm); 

onalrmO; 

for  (;;)  { 

struct  whod  wd; 

int  cc,  whod,  len  =  siseof  (from); 


} 


cc  =  recvfrom(s,  (char  ♦)&wd,  sizeof  (struct  whod),  0,  &from,  &len); 
if  (cc  <=  0)  { 

if  (cc  <  0  errno  !—  EINTR) 
perror(”rwhod:  recv”); 
continue; 

if  (from.sin_port  !=  8p->8_port)  { 

fprintf(stderr,  "rwhod:  %d:  bad  from  port\n”, 
atohs(from  .sin_port)); 
continue; 

} 

if  (!verify(wd.wd_hostname))  {  ^ 

fprintf(stderr,  "rwhod:  malformed  host  name  from  %x\n”, 

ntohl(from.sin_addr.a_addr)); 

continue; 

(void)  sprintf(path,  "^s/whod-^Ss”,  RWHODIR,  wd.wd.hostname); 
whod  =  open(path,  0_FWRONLY|0_FCREATEjO_J'’TRUNCATE,  0665); 

(void)  time(&wd.wd_recvtime); 

(void)  write(whod,  (char  *)fcwd,  cc); 

(void)  close(whod); 


Figure  4.  rwho  server* 


change  of  information. 
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The  second  problem  with  the  current  scheme  is  that  the  rwho  process  services  only  a  single  local 
network,  and  this  network  is  found  by  reading  a  file.  It  is  important  that  software  operating  in 
a  distributed  environment  not  have  any  site>dependent  information  compiled  into  it.  This 
would  require  a  separate  copy  of  the  server  at  each  host  and  make  maintenance  a  severe 
headache.  The  Sun  system  attempts  to  isolate  host-specific  information  from  applications  by 
providing  system  calls  which  return  the  necessary  information!.  The  rwho  server  perforins  a 
lookup  in  a  file  to  find  its  local  network.  A  better,  though  still  unsatisfactory,  scheme  used  by 
the  routing  process  is  to  interrogate  the  system  data  structures  to  locate  those  directly  con¬ 
nected  networks.  A  mechanism  to  acquire  this  information  from  the  system  would  be  a  useful 
addition. 


^  t  An  example  of  such  s  system  call  is  the  call  which  returns  the  host’s  “official” 

name. 
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5.  Advanced  Topics 

A  number  of  facilities  have  yet  to  be  discussed.  For  most  users  of  the  ipc  the  mechanisms 
already  described  will  suffice  in  constructing  distributed  applications.  However,  others  will  find 
need  to  utilize  some  of  the  features  which  we  consider  in  this  section. 

5.1.  Out  of  Band  Data 

The  stream  socket  abstraction  includes  the  notion  of  “out  of  band”  data.  Out  of  band  data  is  a 
logically  independent  transmission  channel  associated  with  each  pair  of  connected  stream  sock* 
ets.  Out  of  band  data  is  delivered  to  the  user  independently  of  normal  data  along  with  the 
SIGURG  signal.  In  addition  to  the  information  passed,  a  logical  mark  is  placed  in  the  data 
stream  to  indicate  the  point  at  which  the  out  of  band  data  was  sent.  The  remote  login  and 
remote  shell  applications  use  this  facility  to  propagate  signals  from  between  client  and  server 
processes.  When  a  signal  is  expected  to  flush  any  pending  output  from  the  remote  process(es), 
all  data  up  to  the  mark  in  the  data  stream  is  discarded. 

The  stream  abstraction  defines  that  the  out  of  band  data  facilities  must  support  the  reliable 
delivery  of  at  least  one  out  of  band  message  at  a  time.  This  message  may  contain  at  least  one 
byte  of  data,  and  at  least  one  message  may  be  pen<Ung  delivery  to  the  user  at  any  one  time. 
For  communications  protocols  which  support  only  in-band  signaling  (that  is,  the  urgent  data  is 
delivered  in  sequence  with  the  normal  data)  the  system  extracts  the  data  from  the  normal  data 
stream  and  stores  it  separately.  This  allows  users  to  choose  between  receiving  the  urgent  data 
in  order  and  receiving  it  out  of  sequence  without  having  to  buffer  all  the  intervening  data. 

To  send  an  out  of  band  message  the  MSGjOOB  flag  is  supplied  to  a  tend  or  sendto  calls,  while 
to  receive  out  of  band  data  MSG_OOB  should  be  indicated  when  performing  a  reevfrom  or  recv 
call.  To  find  out  if  the  read  pointer  is  currently  pointing  at  the  mark  in  the  data  stream,  the 
SIOCATMARK  ioctl  is  provided: 

ioctI(s,  SIOCATMARK,  &yes); 

If  yea  is  a  1  on  return,  the  next  read  will  return  data  after  the  mark.  Otherwise  (assuming  out 
of  band  data  has  arrived),  the  next  read  will  provide  data  sent  by  the  client  prior  to  transmis¬ 
sion  of  the  out  of  band  signal.  The  routine  used  in  the  remote  login  process  to  flush  output  on 
receipt  of  an  interrupt  or  quit  signal  is  shown  in  Figure  5. 


5.2.  Signals  and  Process  Groups 

Due  to  the  existence  of  the  SIGURG  and  SIGIO  signals  each  socket  has  an  associated  process 
group  (just  as  is  done  for  terminals).  This  process  group  is  initialized  to  the  process  group  of  its 
creator,  but  may  be  redefined  at  a  later  time  with  the  SIOCSPGRP  ioctl: 
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oob() 

{ 

int  out  =  1+  1; 

char  wastefBUFSIZ],  mark; 

8ignal(SIGURG,  oob); 

J*  flush  local  terminal  input  and  output  *f 
ioctl(l,  TIOCFLUSH,  (char  •)&out); 

for  (;;)  { 

if  (ioctl(rem,  SIOCATMARK,  £;mark)  <  0)  { 
perror(”ioctr); 
break; 

} 

if  (mark) 
break; 

(void)  read(rem,  watste,  sizeof  (iraste)); 

> 

recv(rem,  &mark,  1,  MSG_OOB); 

} 

Figure  5.  Flushing  terminal  i/o  on  receipt  of  out  of  band  data. 
ioctl(s,  SIOCSPGRP,  &pgrp); 

A  similar  ioctl,  SIOCGPGRP,  is  available  for  determining  the  current  process  group  of  a  socket. 

5.3.  Pseudo  Terminals 

Many  programs  vrill  not  function  properly  vrithout  a  terminal  for  standard  input  and  output. 
Since  a  socket  is  not  a  terminal,  it  is  often  necessary  to  have  a  process  communicating  over  the 
network  do  so  through  a  peettdo  terminal  A  pseudo  terminal  is  actually  a  pair  of  devices,  mas¬ 
ter  and  slave,  which  allow  a  process  to  serve  as  an  active  agent  in  communication  between 
processes  and  users.  Data  written  on  the  slave  side  of  a  pseudo  terminal  is  supplied  as  input  to 
a  process  reading  from  the  master  side.  Data  written  on  the  master  side  is  given  the  slave  as 
input.  In  this  way,  the  process  manipulating  the  master  side  of  the  pseudo  terminal  has  control 
over  the  information  read  and  written  on  the  slave  side.  The  remote  login  server  uses  pseudo 
terminals  for  remote  login  sessions.  A  user  logging  in  to  a  machine  across  the  network  is  pro¬ 
vided  a  shell  with  a  slave  pseudo  terminal  as  standard  input,  output,  and  error.  The  server  pro¬ 
cess  then  handles  the  communication  between  the  programs  invoked  by  the  remote  shell  and  the 
user’s  local  client  process.  When  a  user  sends  an  interrupt  or  quit  signal  to  a  process  executing 
on  a  remote  machine,  the  client  login  program  traps  the  signal,  sends  an  out  of  band  message  to 
the  server  process  who  then  uses  the  signal  number,  sent  as  the  data  value  in  the  out  of  band 
message,  to  perform  a  ktY/p{|(2)  on  the  appropriate  process  group. 
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5.4.  Internet  Address  Binding 

Binding  addresses  to  sockets  in  the  Internet  domain  can  be  fairly  complex.  Communicating 
processes  are  bound  by  an  associafion.  An  association  is  composed  of  local  and  foreign 
addresses,  and  local  and  foreign  ports.  Port  numbers  are  allocated  out  of  separate  spaces,  one 
for  each  Internet  protocol.  Associations  are  always  unique.  That  is,  there  may  never  be  dupli¬ 
cate  <protocoI,  local  address,  local  port,  foreign  address,  foreign  port>  tuples. 

The  bind  system  call  allows  a  process  to  specify  half  of  an  association,  <locaI  address,  local 
port>,  while  the  connect  and  accept  primitives  are  used  to  complete  a  socket’s  association. 
Since  the  association  is  created  in  two  steps  the  association  uniqueness  requirement  indicated 
above  could  be  violated  unless  care  is  taken.  Further,  it  is  unrealistic  to  expect  user  programs 
to  always  know  proper  values  to  use  for  the  local  address  and  local  port  since  a  host  may  reside 
on  multiple  networks  and  the  set  of  allocated  port  numbers  is  not  directly  accessible  to  a  user. 

To  simplify  local  address  binding  the  notion  of  a  “wildcard”  address  has  been  provided.  When 
an  address  is  specified  as  1NADDR_ANY  (a  manifest  constant  defined  in  <netinet/in.h>),  the 
system  interprets  the  address  as  “any  valid  address”.  For  example,  to  bind  a  specific  port 
number  to  a  socket,  but  leave  the  local  address  unspecified,  the  following  code  might  be  used: 

^include  <sys/types.h> 

#include  <netinet/in.h> 

struct  sockaddrjn  sin; 

s  =  socket(AFJNET,  SOCK.STREAM,  0); 
sin.sin_family  —  AF_INET; 
sin.sin_addr.s_addr  =  INADDR_ANY; 
sin.sin_port  =  MYPORT; 
bind(s,  (char  *)&sin,  sizeof  (sin)); 

Sockets  with  wildcarded  local  addresses  may  receive  messages  directed  to  the  specified  port 
number,  and  addressed  to  any  of  the  possible  addresses  assigned  a  host.  For  example,  if  a  host 
is  on  networks  46  and  10  and  a  socket  is  bound  as  above,  then  an  accept  call  is  performed,  the 
process  will  be  able  to  accept  connection  requests  which  arrive  either  from  network  40  or  net¬ 
work  10. 

In  a  similar  fashion,  a  local  port  may  be  left  unspecified  (specified  as  zero),  in  which  case  the 
system  will  select  an  appropriate  port  number  for  it.  For  example: 

sin.sin_addr.s_addr  =  MYADDRESS; 

3in.sin_port  =  0; 

bind(s,  (char  *)&sin,  sizeof  (sin)); 

The  system  selects  the  port  number  based  on  two  criteria.  The  first  is  that  ports  numbered  0 
through  IPPORT_RESERVED-l  are  reserved  for  privileged  users  (that  is,  the  super  user).  The 
second  is  that  the  port  number  is  not  currently  bound  to  some  other  socket.  In  order  to  find  a 
free  port  number  in  the  privileged  range  the  following  code  is  used  by  the  remote  shell  server: 
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struct  sockaddrjn  sin; 


Iport  =  IPPORT_RESERVED  -  1; 

8in.8in_addr.s_addr  =  INADDR_ANY; 

sin.sin_port  —  htons((u_short)lport); 
if  (bind(s,  (caddrjt)&sin,  sieeof  (sin))  >“  0) 
break; 

if  (errno  f=  EADDRINUSE  &&  errno  !—  EADDRNOTAVAIL)  { 
perror(”  socket” ); 
break; 

} 

Iport—; 

if  (Iport  =«*  IPPORT_RESERVED/2)  { 

fprintf(stderr,  ”  socket:  All  ports  in  use\n”); 
break; 

} 

} 

The  restriction  on  allocating  ports  was  done  to  allow  processes  executing  in  a  “secure”  environ¬ 
ment  to  perform  authentication  based  on  the  originating  address  and  port  number. 

In  certain  cases  the  algorithm  used  by  the  system  in  selecting  port  numbers  is  unsuitable  for  an 
application.  This  is  due  to  associations  being  created  in  a  two  step  process.  For  example,  the 
Internet  file  transfer  protocol,  FTP,  specifies  that  data  connections  must  always  originate  from 
the  same  local  port.  However,  duplicate  associations  are  avoided  by  connecting  to  different 
foreign  ports.  In  this  situation  the  system  would  disallow  binding  the  same  local  address  and 
port  number  to  a  socket  if  a  previous  data  connection’s  socket  were  around.  To  override  the 
default  port  selection  algorithm  then  an  option  call  most  be  performed  prior  to  address  binding: 

setsockopt(s,  SOL_SOCKET,  SO_REUSEADDR,  (char  *)0,  0); 
bind(s,  (char  *)&sin,  sizeof  (sin)); 

With  the  above  call,  local  addresses  may  be  bound  which  are  already  in  use.  This  does  not 
violate  the  uniqueness  requirement  as  the  system  still  checks  at  connect  time  to  be  sure  any 
other  sockets  with  the  same  local  address  and  port  do  not  have  the  same  foreign  address  and 
port  (if  an  association  already  exists,  the  error  EADDRINUSE  is  returned). 

Local  address  binding  by  the  system  is  currently  done  somewhat  haphazardly  when  a  host  is  on 
multiple  networks.  Logically ,,one  would  expect  the  system  to  bind  the  local  address  associated 
with  the  network  through  which  a  peer  was  communicating.  For  instance,  if  the  local  host  is 
connected  to  networks  46  and  10  and  the  foreign  host  is  on  network  32,  and  traffic  from  net¬ 
work  82  were  arriving  via  network  10,  the  local  address  to  be  bound  would  be  the  host’s  address 
on  network  10,  not  network  46.  This  unfortunately,  is  not  always  the  case.  For  reasons  too 
complicated  to  discuss  here,  the  local  address  bound  may  be  appear  to  be  chosen  at  random. 
This  property  of  local  address  binding  will  normally  be  invisible  to  users  unless  the  foreign  host 
does  not  understand  how  to  reach  the  address  selected*. 


^  *  For  example,  if  network  48  were  unknown  to  the  host  on  network  32,  and  the  local  address 
were  bound  to  that  located  on  network  48,  then  even  though  a  route  between  the  two  hosts  existed 
through  network  10,  a  connection  would  f^. 
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5.5.  Broadcasting  and  Datagram  Sockets 

By  using  a  datagram  socket  it  is  possible  to  send  broadcast  packets  on  many  networks  sup¬ 
ported  by  the  system  (the  network  itself  must  support  the  notion  of  broadcasting;  the  system 
provides  no  broadcast  simulation  in  software).  Broadcast  messages  can  place  a  high  load  on  a 
network  since  they  force  every  host  on  the  network  to  service  them. 

To  send  a  broadcast  message,  an  Internet  datagram  socket  should  be  created: 

s  =  socket(AFJNET,  SOCK_DGRAM,  0); 

and  at  least  a  port  number  should  be  bound  to  the  socket: 

sin.8in_family  =  AFJNET; 
sin.3in_addr.s_addr  =  INADDR_ANY; 
sin.sin_port  =  MYPORT; 
bind(s,  (char  4^)&sin,  sizeof  (sin)); 

Then  the  message  should  be  addressed  as: 

d8t.sin_family  =  AFJNET; 
inet_makeaddr(net,  INADDR_ANY); 
d3t.sin_port  =  DESTPORT; 

and,  finally,  a  sendto  call  may  be  used: 

sendto(s,  buf,  buflen,  0,  &dst,  sizeof  (dst)); 

Received  broadcast  messages  contain  the  senders  address  and  port  (datagram  sockets  are 
anchored  before  a  message  is  allowed  to  go  out). 

There  are  a  couple  of  minor  problems  in  the  above  example.  One  is  created  because 
INADDRjyw  has  two  meanings: 

1.  Fill  in  my  own  address,  and, 

2.  Broadcast. 

Unfortunately,  broadcast  must  at  some  time  in  the  future  be  changed  to  -1  instead  of  0,  so  that 
bro£idcast  will  no  longer  be  The  second  problem  is  how  do  you  get  your  net  number?  You  could 
use  the  SIOCGICONF  ioctl  call,  or  you  could  get  your  own  address  and  do  a  inetjnetof  on  that. 
INADDRJU^. 

5.6.  Signals 

Two  new  signals  have  been  added  to  the  system  which  may  be  used  in  conjunction  with  the 
interprocess  communication  facilities.  The  SIGURG  signal  is  associated  with  the  existence  of  an 
“urgent  condition”.  The  SIGIO  signal  is  used  with  “interrupt  driven  i/o”  (not  presently  imple¬ 
mented).  SIGURG  is  currently  supplied  a  process  when  out  of  band  data  is  present  at  a  socket. 
If  multiple  sockets  have  out  of  band  data  aw  anting  delivery,  a  select  call  may  be  used  to  deteiv 
mine  those  sockets  with  such  data. 

An  old  signal  which  is  useful  when  constructing  server  processes  is  SIGCHLD.  This  signal  is 
delivered  to  a  process  when  any  children  processes  have  changed  state.  Normally  servers  use 
the  signal  to  “reap”  child  processes  after  exiting.  For  example,  the  remote  login  server  loop 
shown  in  Figure  2  may  be  augmented  as  follows: 
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int  reaper(); 

8ignaI(SIGCHLD,  reaper); 

Iisten(f,  10); 
for  (;;)  { 

int  g,  len  »  sizeof  (from); 

g  =  accept(f,  &from,  &Ien,  0); 
if(g<0){ 

if(ermo!=EINTR) 

perror("rlogind:  accept" ); 
continue; 

} 

} 

^include  <'wait.h> 
reaper() 

{ 

umon  wait  status; 

while  (wait3(&status,  WNOHANG,  0)  >  0) 

t 

} 

If  the  parent  server  process  fails  to  reap  its  children,  a  large  number  of  “zombie”  processes  may 
be  created. 
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